Images
v4.176.0 List images GET
https://api.linode.com/v4/images
Returns a paginated list of Images.
Public Images have IDs that begin with “linode/”. These distribution images are generally available to all users.
Private Images have IDs that begin with “private/”. These Images are Account-specific and only accessible to Users with appropriate Grants .
To view only public Images, call this operation with or without authentication. To view private Images as well, call this operation with authentication.
Authorizations personalAccessToken oauth images:read_only
Query Parameters page Type: integer
>=
1Default:
1
Default: 1 The page of a collection to return.
page_size Type: integer
25..500Default:
100
Default: 100 The number of items to return per page.
Request Samples
Shell
CLI
# Returns public Images only
curl https://api.linode.com/v4/images
# Returns private and public Images
curl -H "Authorization: Bearer $TOKEN " \
Response Samples
200
default
{
"data" : [
{
"capabilities" : [
"cloud-init"
],
"created" : "2021-08-14T22:44:02" ,
"created_by" : "linode" ,
"deprecated" : false ,
"description" : "Example Image description." ,
"eol" : "2026-07-01T04:00:00" ,
"expiry" : null ,
"id" : "linode/debian11" ,
"is_public" : true ,
"label" : "Debian 11" ,
"size" : 2500 ,
"status" : "available" ,
"type" : "manual" ,
"updated" : "2021-08-14T22:44:02" ,
"vendor" : "Debian"
}
],
"page" : 1 ,
"pages" : 1 ,
"results" : 1
}
{
"errors" : [
{
"field" : "fieldname" ,
"reason" : "fieldname must be a valid value"
}
]
}
Responses
200
default
A paginated list of Images.
array
of objects
array
of strings
Read-only A list containing the following possible capabilities of this Image:
cloud-init: This Image supports cloud-init with Metadata . Only applies to public Images.
string<date-time>
Read-only When this Image was created.
string
Read-only The name of the User who created this Image, or “linode”
for public Images.
boolean
Read-only Whether or not this Image is deprecated. Will only be
true for deprecated public Images.
string
1..65000
characters
A detailed description of this Image.
string<date-time>
Read-only The date of the public Image’s planned end of life. null
for private Images.
string<date-time>
Read-only Only Images created automatically from a deleted Linode
(type=automatic) will expire. null for private Images.
string
Read-only The unique ID of this Image.
boolean
Read-only True if the Image is a public distribution image. False
if Image is private Account-specific Image.
string
A short description of the Image.
integer
Read-only The minimum size this Image needs to deploy. Size is in
MB.
stringEnum:
creating
pending_upload
available
Read-only The current status of this Image.
Only Images in an “available” status can be deployed. Images in a “creating” status are being created from a Linode Disk, and will become “available” shortly. Images in a “pending_upload” status are waiting for data to be uploaded , and become “available” after the upload and processing are complete.
The “+order_by” and “+order” operators are not available for filtering on this key.
stringEnum:
manual
automatic
Read-only How the Image was created.
“Manual” Images can be created at any time.
“Automatic” Images are created automatically from a deleted Linode.
string<date-time>
Read-only When this Image was last updated.
string
Read-only The upstream distribution vendor. null for private Images.
integer
Read-only The current page .
integer
Read-only The total number of pages .
integer
Read-only The total number of results.
Error
array
of objects
string
The field in the request that caused this error. This may be a path,
separated by periods in the case of nested fields. In
some cases this may come back as “null” if the error is
not specific to any single element of the request.
string
What happened to cause this error. In most cases, this can be fixed
immediately by changing the data you sent in the request,
but in some cases you will be instructed to Open a support
ticket
or perform some other action before you can complete the
request successfully.
Create an image POST
https://api.linode.com/v4/images
Captures a private gold-master Image from a Linode Disk.
Note . Images are not encrypted even when they are taken from an encrypted disk. When a compute instance is rebuilt from an image, and if the instance has disk encryption enabled, the disk is automatically encrypted.
CLI .
linode-cli images create
Learn more…
OAuth .
images:read_write
linodes:read_only
```
[Learn more...](https://techdocs.akamai.com/linode-api/reference/oauth)Authorizations personalAccessToken oauth images:read_write,linodes:read_only
Request Samples
Shell
CLI
curl -H "Content-Type: application/json" \
"Authorization: Bearer $TOKEN " \
'{
"disk_id": 123,
"label": "this_is_a_label",
"description": "A longer description of the image"
}' \
linode-cli images create \
\
"A longer description \
of the image" \
123
Request Body Schema boolean
Whether this Image supports cloud-init.
string
A detailed description of this Image.
integer
The ID of the Linode Disk that this Image will be created from.
string
A short title of this Image. Defaults to the label of the Disk it is being created from
if not provided.
Response Samples
200
default
{
"capabilities" : [
"cloud-init"
],
"created" : "2021-08-14T22:44:02" ,
"created_by" : "linode" ,
"deprecated" : false ,
"description" : "Example Image description." ,
"eol" : "2026-07-01T04:00:00" ,
"expiry" : null ,
"id" : "linode/debian11" ,
"is_public" : true ,
"label" : "Debian 11" ,
"size" : 2500 ,
"status" : "available" ,
"type" : "manual" ,
"updated" : "2021-08-14T22:44:02" ,
"vendor" : "Debian"
}
{
"errors" : [
{
"field" : "fieldname" ,
"reason" : "fieldname must be a valid value"
}
]
}
Responses
200
default
New private Image created successfully.
array
of strings
Read-only A list containing the following possible capabilities of this Image:
cloud-init: This Image supports cloud-init with Metadata . Only applies to public Images.
string<date-time>
Read-only When this Image was created.
string
Read-only The name of the User who created this Image, or “linode” for public Images.
boolean
Read-only Whether or not this Image is deprecated. Will only be true for deprecated
public Images.
string
1..65000
characters
A detailed description of this Image.
string<date-time>
Read-only The date of the public Image’s planned end of life. null for private
Images.
string<date-time>
Read-only Only Images created automatically from a deleted Linode (type=automatic)
will expire. null for private Images.
string
Read-only The unique ID of this Image.
boolean
Read-only True if the Image is a public distribution image. False if Image
is private Account-specific Image.
string
A short description of the Image.
integer
Read-only The minimum size this Image needs to deploy. Size is in MB.
stringEnum:
creating
pending_upload
available
Read-only The current status of this Image.
Only Images in an “available” status can be deployed. Images in a “creating” status are being created from a Linode Disk, and will become “available” shortly. Images in a “pending_upload” status are waiting for data to be uploaded , and become “available” after the upload and processing are complete.
The “+order_by” and “+order” operators are not available for filtering on this key.
stringEnum:
manual
automatic
Read-only How the Image was created.
“Manual” Images can be created at any time.
“Automatic” Images are created automatically from a deleted Linode.
string<date-time>
Read-only When this Image was last updated.
string
Read-only The upstream distribution vendor. null for private Images.
Error
array
of objects
string
The field in the request that caused this error. This may be a path,
separated by periods in the case of nested fields. In
some cases this may come back as “null” if the error is
not specific to any single element of the request.
string
What happened to cause this error. In most cases, this can be fixed
immediately by changing the data you sent in the request,
but in some cases you will be instructed to Open a support
ticket
or perform some other action before you can complete the
request successfully.
Upload an image POST
https://api.linode.com/v4/images/upload
Initiates an Image upload.
This operation creates a new private Image object and returns it along with the URL to which image data can be uploaded.
Image data must be uploaded within 24 hours of creation or the upload will be canceled and the image deleted.
Image uploads should be made as an HTTP PUT request to the URL returned in the upload_to response parameter, with a Content-type: application/octet-stream header included in the request. For example:
curl -v \
-H "Content-Type: application/octet-stream" \
--upload-file example.img.gz \
$UPLOAD_URL \
--progress-bar \
--output /dev/null
Uploaded image data should be compressed in gzip (.gz) format. The uncompressed disk should be in raw disk image (.img) format. A maximum compressed file size of 5GB is supported for upload at this time.
To initiate and complete an Image upload in a single step, see our guide on how to Upload an Image using Cloud Manager or the Linode CLI image-upload plugin.
Note . Images are not encrypted even when they are taken from an encrypted disk. When a compute instance is rebuilt from an image, and if the instance has disk encryption enabled, the disk is automatically encrypted.
Authorizations personalAccessToken oauth images:read_write
Request Samples
Shell
CLI
curl -H "Content-Type: application/json" \
"Authorization: Bearer $TOKEN " \
'{
"description": "Optional details about the Image",
"label": "Example Image",
"region": "us-east"
}' \
# Upload the Image file in a single step
linode-cli image-upload \
"Optional details about the Image" \
"Example Image" \
\
# Returns the upload_to URL
linode-cli images upload \
"Optional details about the Image" \
"Example Image" \
Request Body Schema boolean
Whether the uploaded Image supports cloud-init.
string
Description for the uploaded Image.
string
Label for the uploaded Image.
string
The region to upload to. Once uploaded, the Image can be used in any region.
Response Samples
200
default
{
"image" : {
"capabilities" : [
"cloud-init"
],
"created" : "2021-08-14T22:44:02" ,
"created_by" : "linode" ,
"deprecated" : false ,
"description" : "Example Image description." ,
"eol" : "2026-07-01T04:00:00" ,
"expiry" : null ,
"id" : "linode/debian11" ,
"is_public" : true ,
"label" : "Debian 11" ,
"size" : 2500 ,
"status" : "available" ,
"type" : "manual" ,
"updated" : "2021-08-14T22:44:02" ,
"vendor" : "Debian"
},
"upload_to" : null
}
{
"errors" : [
{
"field" : "fieldname" ,
"reason" : "fieldname must be a valid value"
}
]
}
Responses
200
default
Image Upload object including the upload URL and Image object.
object
Image object
array
of strings
Read-only A list containing the following possible capabilities of this Image:
cloud-init: This Image supports cloud-init with Metadata . Only applies to public Images.
string<date-time>
Read-only When this Image was created.
string
Read-only The name of the User who created this Image, or “linode” for
public Images.
boolean
Read-only Whether or not this Image is deprecated. Will only be true for deprecated
public Images.
string
1..65000
characters
A detailed description of this Image.
string<date-time>
Read-only The date of the public Image’s planned end of life. null for
private Images.
string<date-time>
Read-only Only Images created automatically from a deleted Linode (type=automatic)
will expire. null for private Images.
string
Read-only The unique ID of this Image.
boolean
Read-only True if the Image is a public distribution image. False if Image
is private Account-specific Image.
string
A short description of the Image.
integer
Read-only The minimum size this Image needs to deploy. Size is in MB.
stringEnum:
creating
pending_upload
available
Read-only The current status of this Image.
Only Images in an “available” status can be deployed. Images in a “creating” status are being created from a Linode Disk, and will become “available” shortly. Images in a “pending_upload” status are waiting for data to be uploaded , and become “available” after the upload and processing are complete.
The “+order_by” and “+order” operators are not available for filtering on this key.
stringEnum:
manual
automatic
Read-only How the Image was created.
“Manual” Images can be created at any time.
“Automatic” Images are created automatically from a deleted Linode.
string<date-time>
Read-only When this Image was last updated.
string
Read-only The upstream distribution vendor. null for private Images.
string
The URL to upload the Image to.
Error
array
of objects
string
The field in the request that caused this error. This may be a path,
separated by periods in the case of nested fields. In
some cases this may come back as “null” if the error is
not specific to any single element of the request.
string
What happened to cause this error. In most cases, this can be fixed
immediately by changing the data you sent in the request,
but in some cases you will be instructed to Open a support
ticket
or perform some other action before you can complete the
request successfully.
Delete an image DELETE
https://api.linode.com/v4/images/{imageId}
Deletes a private Image you have permission to read_write.
Deleting an Image is a destructive action and cannot be undone.
Authorizations personalAccessToken oauth images:read_write
Path Parameters imageId string
Required ID of the Image to look up.
Request Samples
Shell
CLI
curl -H "Authorization: Bearer $TOKEN " \
\
linode-cli images delete 12345
Response Samples
200
default
{
"errors" : [
{
"field" : "fieldname" ,
"reason" : "fieldname must be a valid value"
}
]
}
Responses
200
default
Error
array
of objects
string
The field in the request that caused this error. This may be a path,
separated by periods in the case of nested fields. In
some cases this may come back as “null” if the error is
not specific to any single element of the request.
string
What happened to cause this error. In most cases, this can be fixed
immediately by changing the data you sent in the request,
but in some cases you will be instructed to Open a support
ticket
or perform some other action before you can complete the
request successfully.
Get an image GET
https://api.linode.com/v4/images/{imageId}
Get information about a single Image.
Public Images have IDs that begin with “linode/”. These distribution images are generally available to all users.
Private Images have IDs that begin with “private/”. These Images are Account-specific and only accessible to Users with appropriate Grants .
To view a public Image, call this operation with or without authentication. To view a private Image, call this operation with authentication.
Authorizations personalAccessToken oauth images:read_only
Path Parameters imageId string
Required ID of the Image to look up.
Request Samples
Shell
CLI
# Public Image
curl https://api.linode.com/v4/images/linode/debian11
# Private Image
curl -H "Authorization: Bearer $TOKEN " \
linode-cli images view linode/debian9
Response Samples
200
default
{
"capabilities" : [
"cloud-init"
],
"created" : "2021-08-14T22:44:02" ,
"created_by" : "linode" ,
"deprecated" : false ,
"description" : "Example Image description." ,
"eol" : "2026-07-01T04:00:00" ,
"expiry" : null ,
"id" : "linode/debian11" ,
"is_public" : true ,
"label" : "Debian 11" ,
"size" : 2500 ,
"status" : "available" ,
"type" : "manual" ,
"updated" : "2021-08-14T22:44:02" ,
"vendor" : "Debian"
}
{
"errors" : [
{
"field" : "fieldname" ,
"reason" : "fieldname must be a valid value"
}
]
}
Responses
200
default
A single Image object.
array
of strings
Read-only A list containing the following possible capabilities of this Image:
cloud-init: This Image supports cloud-init with Metadata . Only applies to public Images.
string<date-time>
Read-only When this Image was created.
string
Read-only The name of the User who created this Image, or “linode” for public Images.
boolean
Read-only Whether or not this Image is deprecated. Will only be true for deprecated
public Images.
string
1..65000
characters
A detailed description of this Image.
string<date-time>
Read-only The date of the public Image’s planned end of life. null for private
Images.
string<date-time>
Read-only Only Images created automatically from a deleted Linode (type=automatic)
will expire. null for private Images.
string
Read-only The unique ID of this Image.
boolean
Read-only True if the Image is a public distribution image. False if Image
is private Account-specific Image.
string
A short description of the Image.
integer
Read-only The minimum size this Image needs to deploy. Size is in MB.
stringEnum:
creating
pending_upload
available
Read-only The current status of this Image.
Only Images in an “available” status can be deployed. Images in a “creating” status are being created from a Linode Disk, and will become “available” shortly. Images in a “pending_upload” status are waiting for data to be uploaded , and become “available” after the upload and processing are complete.
The “+order_by” and “+order” operators are not available for filtering on this key.
stringEnum:
manual
automatic
Read-only How the Image was created.
“Manual” Images can be created at any time.
“Automatic” Images are created automatically from a deleted Linode.
string<date-time>
Read-only When this Image was last updated.
string
Read-only The upstream distribution vendor. null for private Images.
Error
array
of objects
string
The field in the request that caused this error. This may be a path,
separated by periods in the case of nested fields. In
some cases this may come back as “null” if the error is
not specific to any single element of the request.
string
What happened to cause this error. In most cases, this can be fixed
immediately by changing the data you sent in the request,
but in some cases you will be instructed to Open a support
ticket
or perform some other action before you can complete the
request successfully.
Update an image PUT
https://api.linode.com/v4/images/{imageId}
Updates a private Image that you have permission to read_write.
Authorizations personalAccessToken oauth images:read_write
Path Parameters imageId string
Required ID of the Image to look up.
Request Samples
Shell
CLI
curl -H "Content-Type: application/json" \
"Authorization: Bearer $TOKEN " \
'{
"label": "My gold-master image",
"description": "The detailed description of my Image."
}' \
linode-cli images update private/12345 \
"My gold-master image" \
"The detailed description \
of my Image."
Request Body Schema string
1..65000
characters
A detailed description of this Image.
string
A short description of the Image.
Response Samples
200
default
{
"capabilities" : [
"cloud-init"
],
"created" : "2021-08-14T22:44:02" ,
"created_by" : "linode" ,
"deprecated" : false ,
"description" : "Example Image description." ,
"eol" : "2026-07-01T04:00:00" ,
"expiry" : null ,
"id" : "linode/debian11" ,
"is_public" : true ,
"label" : "Debian 11" ,
"size" : 2500 ,
"status" : "available" ,
"type" : "manual" ,
"updated" : "2021-08-14T22:44:02" ,
"vendor" : "Debian"
}
{
"errors" : [
{
"field" : "fieldname" ,
"reason" : "fieldname must be a valid value"
}
]
}
Responses
200
default
The updated image.
array
of strings
Read-only A list containing the following possible capabilities of this Image:
cloud-init: This Image supports cloud-init with Metadata . Only applies to public Images.
string<date-time>
Read-only When this Image was created.
string
Read-only The name of the User who created this Image, or “linode” for public Images.
boolean
Read-only Whether or not this Image is deprecated. Will only be true for deprecated
public Images.
string
1..65000
characters
A detailed description of this Image.
string<date-time>
Read-only The date of the public Image’s planned end of life. null for private
Images.
string<date-time>
Read-only Only Images created automatically from a deleted Linode (type=automatic)
will expire. null for private Images.
string
Read-only The unique ID of this Image.
boolean
Read-only True if the Image is a public distribution image. False if Image
is private Account-specific Image.
string
A short description of the Image.
integer
Read-only The minimum size this Image needs to deploy. Size is in MB.
stringEnum:
creating
pending_upload
available
Read-only The current status of this Image.
Only Images in an “available” status can be deployed. Images in a “creating” status are being created from a Linode Disk, and will become “available” shortly. Images in a “pending_upload” status are waiting for data to be uploaded , and become “available” after the upload and processing are complete.
The “+order_by” and “+order” operators are not available for filtering on this key.
stringEnum:
manual
automatic
Read-only How the Image was created.
“Manual” Images can be created at any time.
“Automatic” Images are created automatically from a deleted Linode.
string<date-time>
Read-only When this Image was last updated.
string
Read-only The upstream distribution vendor. null for private Images.
Error
array
of objects
string
The field in the request that caused this error. This may be a path,
separated by periods in the case of nested fields. In
some cases this may come back as “null” if the error is
not specific to any single element of the request.
string
What happened to cause this error. In most cases, this can be fixed
immediately by changing the data you sent in the request,
but in some cases you will be instructed to Open a support
ticket
or perform some other action before you can complete the
request successfully.
