Images
v4.96.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. To view only public Images, call this endpoint without authentication.
Private Images have IDs that begin with “private/”. These images are account-specific and only
accessible to users with images:read_only authorization. To view private Images you have access to in
addition to public images, call this endpoint with authentication.
Authorizations Query Parameters page Type: integer
>= 1Default:
1
Default: 1 The page of a collection to return.
page_size Type: integer
25..100Default:
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" : [
{
"created" : "2018-01-01T00:01:01" ,
"created_by" : "linode" ,
"deprecated" : false ,
"description" : null ,
"eol" : "2200-10-23T00:00:00" ,
"expiry" : null ,
"id" : "linode/ubuntu17.10" ,
"is_public" : true ,
"label" : "Ubuntu 17.10" ,
"size" : 2500 ,
"status" : null ,
"type" : "manual" ,
"updated" : "2019-01-02T00:01:01" ,
"vendor" : "Ubuntu"
}
],
"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
string <date-time>
When this Image was created.
string
The name of the User who created this Image, or “linode” for official Images.
boolean
Whether or not this Image is deprecated. Will only be true for deprecated public Images.
string
A detailed description of this Image.
string <date-time>
The date of the image’s planned end of life. Some images, like custom private images, will not have an end of life date. In that case this field will be None.
string <date-time>
Only Images created automatically (from a deleted Linode; type=automatic) will expire.
string
The unique ID of this Image.
boolean
True if the Image is public.
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.
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. None for private Images.
integer
integer
integer
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.
Pricing change: Images will transition to a paid service with a
cost of $0.10/GB per month for each manual Custom Image stored on an
account. This change will be communicated to customers in advance.
Recovery Images, which are generated automatically after a Linode is
deleted and available for a finite period of time, are provided at no
cost.
Authorizations personalAccessToken oauth images:read_write,linodes:read_only
Request Body Schema 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.
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
Response Samples
200
default
{
"created" : "2018-01-01T00:01:01" ,
"created_by" : "somename" ,
"deprecated" : false ,
"description" : "The detailed description of my Image." ,
"eol" : "2200-10-23T00:00:00" ,
"expiry" : "2018-08-01T00:01:01" ,
"id" : "private/67848373" ,
"is_public" : false ,
"label" : "My gold-master image" ,
"size" : 2500 ,
"status" : null ,
"type" : "manual" ,
"updated" : "2019-01-02T00:01:01" ,
"vendor" : null
}
{
"errors" : [
{
"field" : "fieldname" ,
"reason" : "fieldname must be a valid value"
}
]
}
Responses
200
default
New private Image created successfully.
string <date-time>
When this Image was created.
string
The name of the User who created this Image.
boolean
Whether or not this Image is deprecated. Will only be True for deprecated public Images.
string
A detailed description of this Image.
string <date-time>
The date of the image’s planned end of life. Some images, like custom private images, will not have an end of life date. In that case this field will be None.
string <date-time>
Only Images created automatically (from a deleted Linode; type=automatic) will expire.
string
The unique ID of this Image.
boolean
True if the Image is public.
string
A short description of the Image. Labels cannot contain special characters.
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 for the
image, and will become “available” after the upload is complete and
processing occurs.
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. None 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 cancelled 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.
Authorizations personalAccessToken oauth images:read_write
Request Body Schema 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.
Request Samples
Shell
CLI
curl -H "Content-Type: application/json" \
"Authorization: Bearer $TOKEN " \
'{
"description": "This is an example Machine Image.",
"label": "example-machine-image-label",
"region": "us-east"
}' \
linode-cli images upload \
\
"This is an example Machine Image." \
Response Samples
200
default
{
"image" : {
"created" : "2018-01-01T00:01:01" ,
"created_by" : "somename" ,
"deprecated" : false ,
"description" : "The detailed description of my Image." ,
"eol" : "2200-10-23T00:00:00" ,
"expiry" : "2018-08-01T00:01:01" ,
"id" : "private/67848373" ,
"is_public" : false ,
"label" : "My gold-master image" ,
"size" : 2500 ,
"status" : null ,
"type" : "manual" ,
"updated" : "2019-01-02T00:01:01" ,
"vendor" : null
},
"upload_to" : null
}
{
"errors" : [
{
"field" : "fieldname" ,
"reason" : "fieldname must be a valid value"
}
]
}
Responses
200
default
The new Image upload URL.
object
Private Image object
string <date-time>
When this Image was created.
string
The name of the User who created this Image.
boolean
Whether or not this Image is deprecated. Will only be True for deprecated public Images.
string
A detailed description of this Image.
string <date-time>
The date of the image’s planned end of life. Some images, like custom private images, will not have an end of life date. In that case this field will be None.
string <date-time>
Only Images created automatically (from a deleted Linode; type=automatic) will expire.
string
The unique ID of this Image.
boolean
True if the Image is public.
string
A short description of the Image. Labels cannot contain special characters.
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 for the
image, and will become “available” after the upload is complete and
processing occurs.
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. None 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 67848373
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.
Authorizations Path Parameters imageId string
Required ID of the Image to look up.
Request Samples
Shell
CLI
curl https://api.linode.com/v4/images/linode/debian9
linode-cli images view linode/debian9
Response Samples
200
default
{
"created" : "2018-01-01T00:01:01" ,
"created_by" : "somename" ,
"deprecated" : false ,
"description" : "The detailed description of my Image." ,
"eol" : "2200-10-23T00:00:00" ,
"expiry" : "2018-08-01T00:01:01" ,
"id" : "private/67848373" ,
"is_public" : false ,
"label" : "My gold-master image" ,
"size" : 2500 ,
"status" : null ,
"type" : "manual" ,
"updated" : "2019-01-02T00:01:01" ,
"vendor" : null
}
{
"errors" : [
{
"field" : "fieldname" ,
"reason" : "fieldname must be a valid value"
}
]
}
Responses
200
default
A single Image object.
string <date-time>
When this Image was created.
string
The name of the User who created this Image.
boolean
Whether or not this Image is deprecated. Will only be True for deprecated public Images.
string
A detailed description of this Image.
string <date-time>
The date of the image’s planned end of life. Some images, like custom private images, will not have an end of life date. In that case this field will be None.
string <date-time>
Only Images created automatically (from a deleted Linode; type=automatic) will expire.
string
The unique ID of this Image.
boolean
True if the Image is public.
string
A short description of the Image. Labels cannot contain special characters.
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 for the
image, and will become “available” after the upload is complete and
processing occurs.
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. None 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 Body Schema string
A detailed description of this Image.
string
A short description of the Image. Labels cannot contain special characters.
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 for the
image, and will become “available” after the upload is complete and
processing occurs.
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/67848373 \
"My gold-master image" \
"The detailed description \
of my Image."
Response Samples
200
default
{
"created" : "2018-01-01T00:01:01" ,
"created_by" : "somename" ,
"deprecated" : false ,
"description" : "The detailed description of my Image." ,
"eol" : "2200-10-23T00:00:00" ,
"expiry" : "2018-08-01T00:01:01" ,
"id" : "private/67848373" ,
"is_public" : false ,
"label" : "My gold-master image" ,
"size" : 2500 ,
"status" : null ,
"type" : "manual" ,
"updated" : "2019-01-02T00:01:01" ,
"vendor" : null
}
{
"errors" : [
{
"field" : "fieldname" ,
"reason" : "fieldname must be a valid value"
}
]
}
Responses
200
default
The updated image.
string <date-time>
When this Image was created.
string
The name of the User who created this Image.
boolean
Whether or not this Image is deprecated. Will only be True for deprecated public Images.
string
A detailed description of this Image.
string <date-time>
The date of the image’s planned end of life. Some images, like custom private images, will not have an end of life date. In that case this field will be None.
string <date-time>
Only Images created automatically (from a deleted Linode; type=automatic) will expire.
string
The unique ID of this Image.
boolean
True if the Image is public.
string
A short description of the Image. Labels cannot contain special characters.
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 for the
image, and will become “available” after the upload is complete and
processing occurs.
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. None 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.
