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
Default:
1
The page of a collection to return.
page_size
Type:
[integer]
25..500
Default:
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
Types List (
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, which are accessible from the
Regions List (
GET /regions) endpoint.
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 our guide on
Running a Mail Server.
Important: You must be an unrestricted User in order to add or modify tags on Linodes.
Linodes can be created in a number of ways:
Using a Linode Public Image distribution or a Private Image you created based on another Linode.
Access the Images List (
GET /images) endpoint with authentication to view
all available Images.
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 SSH Key Add (
POST /profile/sshkeys) for more information.
Automate system configuration and software installation by providing a base-64 encoded
cloud-config file.
Requires a compatible Image. You can determine compatible Images by checking for cloud-init under capabilities when using Images List (
GET /images).
Requires a compatible Region. You can determine compatible Regions by checking for Metadata under capabilities when using Regions List (
GET /regions).
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.
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
GET /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]
Default:
true
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.
firewall_id
[integer]
The id of the Firewall to attach this Linode to upon creation.
group
[string]
A deprecated property denoting a group label for this Linode.
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.
interfaces
[array]
An array of Network Interfaces to add to this Linode’s Configuration Profile. At least one and up to three Interface objects can exist in this array. The position in the array determines which of the Linode’s network Interfaces is configured:
First [0]: eth0
Second [1]: eth1
Third [2]: eth2
When updating a Linode’s Interfaces, each Interface must be redefined. An empty interfaces array results in a default public type Interface configuration only.
If no public Interface is configured, public IP addresses are still assigned to the Linode but will not be usable without manual configuration.
Note: Changes to Linode Interface configurations can be enabled by rebooting the Linode.
vpc details
See the
VPC documentation guide for its specifications and limitations.
vlan details
Only Next Generation Network (NGN) data centers support VLANs. Use the Regions (
/regions) endpoint to view the capabilities of data center regions. If a VLAN is attached to your Linode and you attempt to migrate or clone it to a non-NGN data center, the migration or cloning will not initiate. If a Linode cannot be migrated or cloned because of an incompatibility, you will be prompted to select a different data center or contact support.
See the
VLANs Overview guide to view additional specifications and limitations.
label
[string]
3..64
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 begin and end with an alphanumeric character.
May only consist of alphanumeric characters, hyphens (-), underscores (_) or periods (.).
Cannot have two hyphens (--), underscores (__) or periods (..) in a row.
metadata
[object]
An object containing user-defined data relevant to the creation of Linodes.
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]
<=
65535
characters
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.
swap_size
[integer]
Default:
512
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
[array]
An array of tags applied to this object. Tags are for organizational purposes only.
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 Samples
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.
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:
SchedulingW0W2W4W6W8W10W12W14W16W18W20W22
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
[string]
A deprecated property denoting a group label for this Linode.
label
[string]
3..64
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 begin and end with an alphanumeric character.
May only consist of alphanumeric characters, hyphens (-), underscores (_) or periods (.).
Cannot have two hyphens (--), underscores (__) or periods (..) in a row.
tags
[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.
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.
Important: 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 Samples
Request Body Schema
label
Required
[string]
1..255
characters
The label for the new snapshot.
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.
The following conditions apply:
Backups may not be restored across Regions.
Only successfully completed Backups that are not undergoing maintenance can be restored.
The Linode that the Backup is being restored to must not itself be in the process of creating a Backup.
Warning: UUID Collisions
When you restore a backup, the restored disk is assigned the same UUID as the original disk. In most cases, this is acceptable and does not cause issues. However, if you attempt to mount both the original disk and the corresponding restore disk at the same time (by assigning them both to devices in your Configuration Profile’s Block Device Assignment), you will encounter a UUID “collision”.
When this happens, the system selects, and mounts, only one of the disks at random. This is due to both disks sharing the same UUID, and your instance may fail to boot since it will not be clear which disk is root. If your system does boot, you will not see any immediate indication if you are booted into the restored disk or the original disk, and you will be unable to access both disks at the same time.
To avoid this, we recommend only restoring a backup to the same Compute Instance if you do not intend on mounting them at the same time or are comfortable modifying UUIDs. If you need access to files on both the original disk and the restored disk simultaneously (such as needing to copy files between them), we suggest either restoring the backup to a separate Compute Instance or
creating a new Compute Instance with the desired backup_id.
To learn more about block device assignments and viewing your disks’ UUIDs, see our guide on
Configuration Profiles.
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 Samples
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.
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 Samples
Request Body Schema
config_id
[integer]
The Linode Config ID to boot into.
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.
Linodes utilizing Metadata ("has_user_data": true) must be cloned to a new Linode with metadata.user_data included with the clone request.
vpc details
If the Linode you are cloning has a vpc purpose Interface on its active Configuration Profile that includes a 1:1 NAT, the resulting clone is configured with an any 1:1 NAT.
See the
VPC documentation guide for its specifications and limitations.
vlan details
Only Next Generation Network (NGN) data centers support VLANs. If a VLAN is attached to your Linode and you attempt clone it to a non-NGN data center, the cloning will not initiate. If a Linode cannot be cloned because of an incompatibility, you will be prompted to select a different data center or contact support.
See the
VLANs Overview guide to view additional specifications and limitations.
Authorizations
personalAccessToken
oauth
linodes:read_write
Path Parameters
linodeId
[integer]Required
ID of the Linode to clone.
Request Samples
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]
3..64
characters
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 the target for the clone, the ID of that Linode. The existing Linode must have enough resources to accept the clone.
metadata
[object]
An object containing user-defined data relevant to the creation of Linodes.
Cannot be modified after provisioning. To update, use either the
Linode Clone or
Linode Rebuild commands.
Must not be included when cloning to an existing Linode.
Unencoded data must not exceed 65535 bytes, or about 16kb encoded.
private_ip
[boolean]
If true, the created Linode will have private networking enabled and assigned a private IPv4 address.
Can only be provided when cloning to a new Linode.
region
[string]
This is the Region where the Linode will be deployed.
To view all available Regions you can deploy to see
GET /regions.
Region can only be provided and is required when cloning to a new Linode.
type
[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 and is required when cloning to a new Linode.
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
Default:
1
The page of a collection to return.
page_size
Type:
[integer]
25..500
Default:
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 Samples
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 until a device exists that allows the boot process to start.
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.
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.
interfaces
[array]
An array of Network Interfaces to add to this Linode’s Configuration Profile. At least one and up to three Interface objects can exist in this array. The position in the array determines which of the Linode’s network Interfaces is configured:
First [0]: eth0
Second [1]: eth1
Third [2]: eth2
When updating a Linode’s Interfaces, each Interface must be redefined. An empty interfaces array results in a default public type Interface configuration only.
If no public Interface is configured, public IP addresses are still assigned to the Linode but will not be usable without manual configuration.
Note: Changes to Linode Interface configurations can be enabled by rebooting the Linode.
vpc details
See the
VPC documentation guide for its specifications and limitations.
vlan details
Only Next Generation Network (NGN) data centers support VLANs. Use the Regions (
/regions) endpoint to view the capabilities of data center regions. If a VLAN is attached to your Linode and you attempt to migrate or clone it to a non-NGN data center, the migration or cloning will not initiate. If a Linode cannot be migrated or cloned because of an incompatibility, you will be prompted to select a different data center or contact support.
See the
VLANs Overview guide to view additional specifications and limitations.
kernel
[string]
Default:
linode/latest-64bit
A Kernel ID to boot a Linode with. Here are examples of commonly-used kernels:
linode/latest-64bit (default): Our latest kernel at the time of instance boot/reboot.
linode/grub2: The upstream distribution-supplied kernel that is installed on the primary disk, or a custom kernel if installed.
linode/direct-disk: The MBR (Master Boot Record) of the primary disk/root device, used instead of a Linux kernel.
For a complete list of options, use the
Kernels List command.
label
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:
defaultsinglebinbash
Defines the state of your Linode after booting. Defaults to default.
virt_mode
[string]
Enum:
paravirtfullvirt
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.
fullvirt affords more customization, but is slower because 100% of the VM
is virtualized.
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.
configId
[integer]Required
The id of the Configuration Profile.
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.
configId
[integer]Required
The id of the Configuration Profile.
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.
configId
[integer]Required
The id of the Configuration Profile.
Request Samples
Request Body Schema
comments
Nullable
[string]
Optional field for arbitrary User comments on this Config.
devices
[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 until a device exists that allows the boot process to start.
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.
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.
interfaces
[array]
An array of Network Interfaces to add to this Linode’s Configuration Profile. At least one and up to three Interface objects can exist in this array. The position in the array determines which of the Linode’s network Interfaces is configured:
First [0]: eth0
Second [1]: eth1
Third [2]: eth2
When updating a Linode’s Interfaces, each Interface must be redefined. An empty interfaces array results in a default public type Interface configuration only.
If no public Interface is configured, public IP addresses are still assigned to the Linode but will not be usable without manual configuration.
Note: Changes to Linode Interface configurations can be enabled by rebooting the Linode.
vpc details
See the
VPC documentation guide for its specifications and limitations.
vlan details
Only Next Generation Network (NGN) data centers support VLANs. Use the Regions (
/regions) endpoint to view the capabilities of data center regions. If a VLAN is attached to your Linode and you attempt to migrate or clone it to a non-NGN data center, the migration or cloning will not initiate. If a Linode cannot be migrated or cloned because of an incompatibility, you will be prompted to select a different data center or contact support.
See the
VLANs Overview guide to view additional specifications and limitations.
kernel
[string]
Default:
linode/latest-64bit
A Kernel ID to boot a Linode with. Here are examples of commonly-used kernels:
linode/latest-64bit (default): Our latest kernel at the time of instance boot/reboot.
linode/grub2: The upstream distribution-supplied kernel that is installed on the primary disk, or a custom kernel if installed.
linode/direct-disk: The MBR (Master Boot Record) of the primary disk/root device, used instead of a Linux kernel.
For a complete list of options, use the
Kernels List command.
label
[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:
defaultsinglebinbash
Defines the state of your Linode after booting. Defaults to default.
virt_mode
[string]
Enum:
paravirtfullvirt
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.
fullvirt affords more customization, but is slower because 100% of the VM
is virtualized.
Response Samples
Responses
Configuration Profile Interfaces List
GET
https://api.linode.com/v4/linode/instances/{linodeId}/configs/{configId}/interfaces
Returns an ordered array of all Interfaces associated with this Configuration Profile.
The User accessing this command must have at least read_only grants to the Linode.
Authorizations
personalAccessToken
oauth
linodes:read_only
Path Parameters
linodeId
[integer]Required
The id of the Linode.
configId
[integer]Required
The id of the Configuration Profile.
Request Samples
Response Samples
Responses
Configuration Profile Interface Add
POST
https://api.linode.com/v4/linode/instances/{linodeId}/configs/{configId}/interfaces
Creates and appends a single Interface to the end of the interfaces array for an existing Configuration Profile.
The User accessing this command must have read_write grants to the Linode.
A successful request triggers a linode_config_update event.
If the new Interface is added with "primary": true, then any existing primary Interface is changed to "primary": false.
Reboot the Linode with this Configuration Profile to activate an Interface that was added with this command.
Authorizations
personalAccessToken
oauth
linodes:read_write
Path Parameters
linodeId
[integer]Required
The id of the Linode.
configId
[integer]Required
The id of the Configuration Profile.
Request Samples
Request Body Schema
active
[boolean]
Returns true if the Interface is in use, meaning that Compute Instance has been booted using the Configuration Profile to which the Interface belongs. Otherwise returns false.
ip_ranges
Nullable
[array]
An array of IPv4 CIDR VPC Subnet ranges that are routed to this Interface.
Array items are only allowed for vpc type Interfaces.
This must be empty for non-vpc type Interfaces.
For requests:
Addresses in submitted ranges must not already be actively assigned.
Submitting values replaces any existing values.
Submitting an empty array removes any existing values.
Omitting this property results in no change to existing values.
ipam_address
Nullable
[string]<ip/netmask>
This Network Interface’s private IP address in Classless Inter-Domain Routing (CIDR) notation.
For vlan purpose Interfaces:
Must be unique among the Linode’s Interfaces to avoid conflicting addresses.
Should be unique among devices attached to the VLAN to avoid conflict.
The Linode is configured to use this address for the associated Interface upon reboot if Network Helper is enabled. If Network Helper is disabled, the address can be enabled with
manual static IP configuration.
For public purpose Interfaces:
In requests, must be an empty string ("") or null if included.
In responses, always returns null.
For vpc purpose Interfaces:
In requests, must be an empty string ("") or null if included.
In responses, always returns null.
ipv4
[object]
IPv4 addresses configured for this Interface. Only allowed for vpc type Interfaces. Returns null if no vpc Interface is assigned.
nat_1_1
Nullable
[string]<ip>
The 1:1 NAT IPv4 address, used to associate a public IPv4 address with the VPC Subnet IPv4 address assigned to this Interface.
Only allowed for vpc type Interfaces.
Returns null if no 1:1 NAT is set for a vpc type Interface.
Returns an empty string ("") for non-vpc type Interfaces.
For requests:
Setting this value to any enables the Linode’s assigned public IPv4 address on this Interface and establishes a 1:1 NAT between the public IPv4 and VPC Subnet IPv4 addresses.
Setting the value to a specific public IPv4 address that is assigned to the Linode enables a 1:1 NAT between that address and the VPC Subnet IPv4 address.
The public IPv4 address can’t be shared with another Linode.
If omitted, set to null, or set to an empty string (""), no 1:1 NAT is established.
Note: When creating a new compute-instance, you can’t set this to a specific IPv4 address. When a new compute instance is created, the network establishes a public IPv4 address for it. Since this address doesn’t exist yet, you can’t include a custom IPv4 address to change it. Once your compute instances is created, you can update your configuration profile interface to change the nat_1_1 address.
vpc
Nullable
[string]<ip>
The VPC Subnet IPv4 address for this Interface.
Only allowed for vpc type Interfaces.
Returns an empty string ("") for non-vpc type Interfaces.
For requests:
Must not already be actively assigned as an address or within a range to any Linodes.
Must not be the first two or last two addresses in the Subnet IPv4 Range.
If omitted, a valid address within the Subnet IPv4 range is automatically assigned.
label
Nullable
[string]
1..64
characters
The name of this Interface.
For vlan purpose Interfaces:
Required.
Must be unique among the Linode’s Interfaces (a Linode cannot be attached to the same VLAN multiple times).
Can only contain ASCII letters, numbers, and hyphens (-). You can’t use two consecutive hyphens (--).
If the VLAN label is new, a VLAN is created. Up to 10 VLANs can be created in each data center region. To view your active VLANs, use the
VLANs List endpoint.
For public purpose Interfaces:
In requests, must be an empty string ("") or null if included.
In responses, always returns null.
For vpc purpose Interfaces:
In requests, must be an empty string ("") or null if included.
In responses, always returns null.
primary
[boolean]
The primary Interface is configured as the default route to the Linode.
Each Configuration Profile can have up to one "primary": true Interface at a time.
Must be false for vlan type Interfaces.
If no Interface is configured as the primary, the first non-vlan type Interface in the interfaces array is automatically treated as the primary Interface.
purpose
Required
[string]
Enum:
publicvlanvpc
The type of Interface.
public
Only one public Interface per Linode can be defined.
The Linode’s default public IPv4 address is assigned to the public Interface.
A Linode must have a public Interface in the first/eth0 position to be reachable via the public internet upon boot without additional system configuration. If no public Interface is configured, the Linode is not directly reachable via the public internet. In this case, access can only be established via
LISH or other Linodes connected to the same VLAN or VPC.
vlan
Configuring a vlan purpose Interface attaches this Linode to the VLAN with the specified label.
The Linode is configured to use the specified ipam_address, if any.
vpc
Configuring a vpc purpose Interface attaches this Linode to the existing VPC Subnet with the specified subnet_id.
When the Interface is activated, the Linode is configured to use an IP address from the range in the assigned VPC Subnet. See ipv4.vpc for more information.
subnet_id
Nullable
[integer]
The id of the VPC Subnet for this Interface.
In requests, this value is used to assign a Linode to a VPC Subnet.
Required for vpc type Interfaces.
Returns null for non-vpc type Interfaces.
Once a VPC Subnet is assigned to an Interface, it cannot be updated.
The Linode must be rebooted with the Interface’s Configuration Profile to complete assignment to a VPC Subnet.
Response Samples
Responses
Configuration Profile Interfaces Order
POST
https://api.linode.com/v4/linode/instances/{linodeId}/configs/{configId}/interfaces/order
Reorders the existing Interfaces of a Configuration Profile.
The User accessing this command must have read_write grants to the Linode.
Authorizations
personalAccessToken
oauth
linodes:read_write
Path Parameters
linodeId
[integer]Required
The id of the Linode.
configId
[integer]Required
The id of the Configuration Profile.
Request Samples
Request Body Schema
ids
Required
[array]
An ordered array of existing Configuration Profile Interface ids.
All current Interface ids must be present in the array.
If the Configuration Profile contains Interfaces and is active on the Linode, the Linode must first be shut down prior to running this command.
Reordering takes effect after rebooting the Linode with this Configuration Profile.
The position in the array determines which of the Linode’s network Interfaces is configured:
Deletes an Interface from the Configuration Profile.
The User accessing this command must have read_write grants to the Linode.
A successful request triggers a linode_config_update event.
Active Interfaces cannot be deleted. The associated Linode must first be shut down (or restarted using another Configuration Profile) before such Interfaces can be deleted from a Configuration Profile.
Authorizations
personalAccessToken
oauth
linodes:read_write
Path Parameters
linodeId
[integer]Required
The id of the Linode.
configId
[integer]Required
The id of the Configuration Profile.
interfaceId
[integer]Required
The id of the Linode Configuration Profile Interface.
Request Samples
Response Samples
Responses
Configuration Profile Interface View
GET
https://api.linode.com/v4/linode/instances/{linodeId}/configs/{configId}/interfaces/{interfaceId}
Returns a single Configuration Profile Interface.
The User accessing this command must have at least read_only grants to the Linode.
Authorizations
personalAccessToken
oauth
linodes:read_only
Path Parameters
linodeId
[integer]Required
The id of the Linode.
configId
[integer]Required
The id of the Configuration Profile.
interfaceId
[integer]Required
The id of the Linode Configuration Profile Interface.
Request Samples
Response Samples
Responses
Configuration Profile Interface Update
PUT
https://api.linode.com/v4/linode/instances/{linodeId}/configs/{configId}/interfaces/{interfaceId}
Updates a vpc or public purpose Interface for this Configuration Profile.
The User accessing this command must have read_write grants to the Linode.
A successful request triggers a linode_config_update event.
The Interface purpose cannot be updated with this command.
VPC Subnets cannot be updated on an Interface. A new vpc purpose Interface must be created to assign a different Subnet to a Configuration Profile.
Only primary can be updated for public purpose Interfaces.
This command not currently allowed for vlan purpose Interfaces.
Authorizations
personalAccessToken
oauth
linodes:read_write
Path Parameters
linodeId
[integer]Required
The id of the Linode.
configId
[integer]Required
The id of the Configuration Profile.
interfaceId
[integer]Required
The id of the Linode Configuration Profile Interface.
Request Samples
Request Body Schema
ip_ranges
Nullable
[array]
An array of IPv4 CIDR VPC Subnet ranges that are routed to this Interface.
Array items are only allowed for vpc type Interfaces.
This must be empty for non-vpc type Interfaces.
For requests:
Addresses in submitted ranges must not already be actively assigned.
Submitting values replaces any existing values.
Submitting an empty array removes any existing values.
Omitting this property results in no change to existing values.
ipv4
[object]
IPv4 addresses configured for this Interface. Only allowed for vpc type Interfaces. Returns null if no vpc Interface is assigned.
nat_1_1
Nullable
[string]<ip>
The 1:1 NAT IPv4 address, used to associate a public IPv4 address with the VPC Subnet IPv4 address assigned to this Interface.
Only allowed for vpc type Interfaces.
Returns null if no 1:1 NAT is set for a vpc type Interface.
Returns an empty string ("") for non-vpc type Interfaces.
For requests:
Setting this value to any enables the Linode’s assigned public IPv4 address on this Interface and establishes a 1:1 NAT between the public IPv4 and VPC Subnet IPv4 addresses.
Setting the value to a specific public IPv4 address that is assigned to the Linode enables a 1:1 NAT between that address and the VPC Subnet IPv4 address.
The public IPv4 address can’t be shared with another Linode.
If omitted, set to null, or set to an empty string (""), no 1:1 NAT is established.
Note: When creating a new compute-instance, you can’t set this to a specific IPv4 address. When a new compute instance is created, the network establishes a public IPv4 address for it. Since this address doesn’t exist yet, you can’t include a custom IPv4 address to change it. Once your compute instances is created, you can update your configuration profile interface to change the nat_1_1 address.
vpc
Nullable
[string]<ip>
The VPC Subnet IPv4 address for this Interface.
Only allowed for vpc type Interfaces.
Returns an empty string ("") for non-vpc type Interfaces.
For requests:
Must not already be actively assigned as an address or within a range to any Linodes.
Must not be the first two or last two addresses in the Subnet IPv4 Range.
If omitted, a valid address within the Subnet IPv4 range is automatically assigned.
primary
[boolean]
The primary Interface is configured as the default route to the Linode.
Each Configuration Profile can have up to one "primary": true Interface at a time.
Must be false for vlan type Interfaces.
If no Interface is configured as the primary, the first non-vlan type Interface in the interfaces array is automatically treated as the primary Interface.
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
Default:
1
The page of a collection to return.
page_size
Type:
[integer]
25..500
Default:
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 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.
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.
Authorizations
personalAccessToken
oauth
linodes:read_write
Path Parameters
linodeId
[integer]Required
ID of the Linode to look up.
Request Samples
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 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]
Enum:
rawswapext3ext4initrd
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
[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.
size
Required
[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.
stackscript_data
[object]
<=
65535
characters
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.
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 Samples
Request Body Schema
label
[string]
1..48
characters
The Disk’s label is for display purposes only.
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 Samples
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.
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 Disk must not be in use. If the Disk is in use, the request will
succeed but the resize will ultimately fail. For a request to succeed,
the Linode must be shut down prior to resizing the Disk, or the Disk
must not be assigned to the Linode’s active Configuration Profile.
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.
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
Request Body Schema
size
Required
[integer]
>=
1
The desired size, in MB, of the disk.
Response Samples
Responses
Firewalls List
GET
https://api.linode.com/v4/linode/instances/{linodeId}/firewalls
View Firewall information for Firewalls assigned to this Linode.
Authorizations
personalAccessToken
oauth
linodes:read_only
Path Parameters
linodeId
[integer]Required
ID of the Linode to access.
Query Parameters
page
Type:
[integer]
>=
1
Default:
1
Default:
1
The page of a collection to return.
page_size
Type:
[integer]
25..500
Default:
100
Default:
100
The number of items to return per page.
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.
Note: If the target Linode has several configuration profiles that include a Virtual Private Cloud (VPC) interface, address information for all of VPCs will be listed in the response.
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 Samples
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.
Deletes a public or private IPv4 address associated with this Linode. This will fail if it is the Linode’s last remaining public IPv4 address, or if the address has a 1:1 NAT with an active VPC Subnet address.
Authorizations
personalAccessToken
oauth
linodes:read_write
Path Parameters
linodeId
[integer]Required
The ID of the Linode.
address
[string]<ip>Required
The IP address.
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.
address
[string]<ip>Required
The IP address.
Request Samples
Response Samples
Responses
IP Address RDNS Update
PUT
https://api.linode.com/v4/linode/instances/{linodeId}/ips/{address}
Updates the reverse DNS (RDNS) for a Linode’s IP Address. This may be done for both IPv4 and IPv6 addresses.
Setting the RDNS to null for a public IPv4 address, resets it to the default “ip.linodeusercontent.com” RDNS value.
Authorizations
personalAccessToken
oauth
linodes:read_write
Path Parameters
linodeId
[integer]Required
The ID of the Linode.
address
[string]<ip>Required
The IP address.
Request Samples
Request Body Schema
rdns
Nullable
Required
[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.
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. See our Pricing Page for Region-specific pricing, which applies after migration is complete. 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.
vpc details
Cross DC migrations are not allowed for Linodes that have a vpc purpose Configuration Profile Interface. Host migrations within the same DC are permitted.
See the
VPC documentation guide for its specifications and limitations.
vlan details
Only Next Generation Network (NGN) data centers support VLANs. Use the Regions (
/regions) endpoint to view the capabilities of data center regions. If a VLAN is attached to your Linode and you attempt to migrate or clone it to a non-NGN data center, the migration or cloning will not initiate. If a Linode cannot be migrated or cloned because of an incompatibility, you will be prompted to select a different data center or contact support.
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.
See the
VLANs Overview guide to view additional specifications and limitations.
Authorizations
personalAccessToken
oauth
linodes:read_write
Path Parameters
linodeId
[integer]Required
ID of the Linode to migrate.
Request Samples
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.
type
[string]
Enum:
warmcold
Default:
cold
Type of migration used in moving to a new host or Linode type.
warm: the Linode will not power down until the migration is complete.
Warm migrations are not available for DC migrations.
cold: the Linode will be powered down and migrated. When the migration
is complete, the Linode will be powered on.
upgrade
[boolean]
Default:
false
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.
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 Samples
Request Body Schema
allow_auto_disk_resize
[boolean]
Default:
true
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.
Response Samples
Responses
Linode NodeBalancers View
GET
https://api.linode.com/v4/linode/instances/{linodeId}/nodebalancers
Returns a list of NodeBalancers that are assigned to this Linode and readable by the requesting User.
Read permission to a NodeBalancer can be given to a User by accessing the User’s Grants Update
(
PUT /account/users/{username}/grants) endpoint.
Authorizations
personalAccessToken
oauth
linodes:read_only
Path Parameters
linodeId
[integer]Required
ID of the Linode to look up
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 Samples
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.
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 Samples
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.
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.
Linodes utilizing Metadata ("has_user_data": true) should include metadata.user_data in the rebuild request to continue using the service.
You also have the option to resize the Linode to a different plan by including the type parameter with your request. Note that resizing involves migrating the Linode to a new hardware host, while rebuilding without resizing maintains the same hardware host. Resizing also requires significantly more time for completion of this command. The following additional conditions apply:
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 rebuild.
Request Samples
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 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.
booted
[boolean]
Default:
true
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 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.
metadata
[object]
An object containing user-defined data relevant to the creation of Linodes.
Cannot be modified after provisioning. To update, use either the
Linode Clone or
Linode Rebuild commands.
Must not be included when cloning to an existing Linode.
Unencoded data must not exceed 65535 bytes, or about 16kb encoded.
root_pass
Required
[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]
<=
65535
characters
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.
type
[string]
The ID of the
Linode Type to resize to with this request.
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 Samples
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.
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.
You can also resize a Linode when using the
Linode Rebuild command.
Authorizations
personalAccessToken
oauth
linodes:read_write
Path Parameters
linodeId
[integer]Required
ID of the Linode to resize.
Request Samples
Request Body Schema
allow_auto_disk_resize
[boolean]
Default:
true
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.
migration_type
[string]
Enum:
warmcold
Default:
cold
Type of migration used in moving to a new host or Linode type.
warm: the Linode will not power down until the migration is complete.
Warm migrations are not available for DC migrations.
cold: the Linode will be powered down and migrated. When the migration
is complete, the Linode will be powered on.
type
Required
[string]
The ID representing the Linode Type.
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..12Required
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..2037Required
Numeric value representing the year to look up.
month
[integer]
1..12Required
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
Default:
1
The page of a collection to return.
page_size
Type:
[integer]
25..500
Default:
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.
Due to the extensive list of available kernels, please keep
pagination controls in mind when managing responses to this command.
Authorizations
Query Parameters
page
Type:
[integer]
>=
1
Default:
1
Default:
1
The page of a collection to return.
page_size
Type:
[integer]
25..500
Default:
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}
