Images
v4.176.0 Images List 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 endpoint with or without authentication. To view private Images as well, call this endpoint 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
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>
When this Image was created.
string
The name of the User who created this Image, or “linode” for public Images.
boolean
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>
The date of the public Image’s planned end of life. null for private Images.
string<date-time>
Only Images created automatically from a deleted Linode (type=automatic) will expire. null for private Images.
string
The unique ID of this Image.
boolean
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
The minimum size this Image needs to deploy. Size is in MB.
stringEnum:
creating
pending_upload
available
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
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>
When this Image was last updated.
string
The upstream distribution vendor. null for private Images.
integer
The current
page
.
integer
The total number of
pages
.
integer
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.
Image Create POST
https://api.linode.com/v4/images
Captures a private gold-master Image from a Linode Disk.
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
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>
When this Image was created.
string
The name of the User who created this Image, or “linode” for public Images.
boolean
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>
The date of the public Image’s planned end of life. null for private Images.
string<date-time>
Only Images created automatically from a deleted Linode (type=automatic) will expire. null for private Images.
string
The unique ID of this Image.
boolean
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
The minimum size this Image needs to deploy. Size is in MB.
stringEnum:
creating
pending_upload
available
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
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>
When this Image was last updated.
string
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.
Image Upload POST
https://api.linode.com/v4/images/upload
Initiates an Image upload.
This endpoint 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.
Note: 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.
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
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>
When this Image was created.
string
The name of the User who created this Image, or “linode” for public Images.
boolean
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>
The date of the public Image’s planned end of life. null for private Images.
string<date-time>
Only Images created automatically from a deleted Linode (type=automatic) will expire. null for private Images.
string
The unique ID of this Image.
boolean
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
The minimum size this Image needs to deploy. Size is in MB.
stringEnum:
creating
pending_upload
available
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
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>
When this Image was last updated.
string
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.
Image Delete 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.
Image View 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 endpoint with or without authentication. To view a private Image, call this endpoint 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
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>
When this Image was created.
string
The name of the User who created this Image, or “linode” for public Images.
boolean
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>
The date of the public Image’s planned end of life. null for private Images.
string<date-time>
Only Images created automatically from a deleted Linode (type=automatic) will expire. null for private Images.
string
The unique ID of this Image.
boolean
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
The minimum size this Image needs to deploy. Size is in MB.
stringEnum:
creating
pending_upload
available
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
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>
When this Image was last updated.
string
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.
Image Update 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
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>
When this Image was created.
string
The name of the User who created this Image, or “linode” for public Images.
boolean
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>
The date of the public Image’s planned end of life. null for private Images.
string<date-time>
Only Images created automatically from a deleted Linode (type=automatic) will expire. null for private Images.
string
The unique ID of this Image.
boolean
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
The minimum size this Image needs to deploy. Size is in MB.
stringEnum:
creating
pending_upload
available
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
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>
When this Image was last updated.
string
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.
