Images v4.176.0
Images List
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 |
The page of a collection to return. |
page_size |
The number of items to return per page. |
Request Samples
# Returns public Images only
curl https://api.linode.com/v4/images
# Returns private and public Images
curl -H "Authorization: Bearer $TOKEN" \
https://api.linode.com/v4/images
linode-cli images list
Response Samples
{
"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
data | array
of objects
| ||||||||||||||||||||||||||||||
page | integer The current page. | ||||||||||||||||||||||||||||||
pages | integer The total number of pages. | ||||||||||||||||||||||||||||||
results | integer The total number of results. |
errors | array
of objects
|
Image Create
Captures a private gold-master Image from a Linode Disk.
Authorizations
personalAccessToken | |
oauth | images:read_write,linodes:read_only |
Request Samples
curl -H "Content-Type: application/json" \
-H "Authorization: Bearer $TOKEN" \
-X POST -d '{
"disk_id": 123,
"label": "this_is_a_label",
"description": "A longer description of the image"
}' \
https://api.linode.com/v4/images
linode-cli images create \
--label this_is_a_label \
--description "A longer description \
of the image" \
--disk_id 123
Request Body Schema
cloud_init | boolean Whether this Image supports cloud-init. |
description | string A detailed description of this Image. |
disk_id Required | integer The ID of the Linode Disk that this Image will be created from. |
label | string A short title of this Image. Defaults to the label of the Disk it is being created from if not provided. |
Response Samples
{
"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
capabilities | array
of strings A list containing the following possible capabilities of this Image:
|
created | string<date-time> When this Image was created. |
created_by | string The name of the User who created this Image, or “linode” for public Images. |
deprecated | boolean Whether or not this Image is deprecated. Will only be true for deprecated public Images. |
description Nullable | string
1..65000
charactersA detailed description of this Image. |
eol Nullable | string<date-time> The date of the public Image’s planned end of life. |
expiry Nullable | string<date-time> Only Images created automatically from a deleted Linode (type=automatic) will expire. |
id | string The unique ID of this Image. |
is_public | boolean True if the Image is a public distribution image. False if Image is private Account-specific Image. |
label | string A short description of the Image. |
size | integer The minimum size this Image needs to deploy. Size is in MB. |
status | string Enum:
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. |
type | string Enum:
manual
automatic How the Image was created. “Manual” Images can be created at any time. “Automatic” Images are created automatically from a deleted Linode. |
updated | string<date-time> When this Image was last updated. |
vendor Nullable | string The upstream distribution vendor. |
errors | array
of objects
|
Image 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 aContent-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
curl -H "Content-Type: application/json" \
-H "Authorization: Bearer $TOKEN" \
-X POST -d '{
"description": "Optional details about the Image",
"label": "Example Image",
"region": "us-east"
}' \
https://api.linode.com/v4/images/upload
# Upload the Image file in a single step
linode-cli image-upload \
--description "Optional details about the Image" \
--label "Example Image" \
--region us-east \
/path/to/image-file.img.gz
# Returns the upload_to URL
linode-cli images upload \
--description "Optional details about the Image" \
--label "Example Image" \
--region us-east
Request Body Schema
cloud_init | boolean Whether the uploaded Image supports cloud-init. |
description | string Description for the uploaded Image. |
label Required | string Label for the uploaded Image. |
region Required | string The region to upload to. Once uploaded, the Image can be used in any region. |
Response Samples
{
"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
image | object Image object
| ||||||||||||||||||||||||||||||
upload_to | string The URL to upload the Image to. |
errors | array
of objects
|
Image Delete
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 RequiredID of the Image to look up. |
Request Samples
curl -H "Authorization: Bearer $TOKEN" \
-X DELETE \
https://api.linode.com/v4/images/private/12345
linode-cli images delete 12345
Response Samples
{}
{
"errors": [
{
"field": "fieldname",
"reason": "fieldname must be a valid value"
}
]
}
Responses
errors | array
of objects
|
Image View
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 RequiredID of the Image to look up. |
Request Samples
# Public Image
curl https://api.linode.com/v4/images/linode/debian11
# Private Image
curl -H "Authorization: Bearer $TOKEN" \
https://api.linode.com/v4/images/private/12345
linode-cli images view linode/debian9
Response Samples
{
"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
capabilities | array
of strings A list containing the following possible capabilities of this Image:
|
created | string<date-time> When this Image was created. |
created_by | string The name of the User who created this Image, or “linode” for public Images. |
deprecated | boolean Whether or not this Image is deprecated. Will only be true for deprecated public Images. |
description Nullable | string
1..65000
charactersA detailed description of this Image. |
eol Nullable | string<date-time> The date of the public Image’s planned end of life. |
expiry Nullable | string<date-time> Only Images created automatically from a deleted Linode (type=automatic) will expire. |
id | string The unique ID of this Image. |
is_public | boolean True if the Image is a public distribution image. False if Image is private Account-specific Image. |
label | string A short description of the Image. |
size | integer The minimum size this Image needs to deploy. Size is in MB. |
status | string Enum:
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. |
type | string Enum:
manual
automatic How the Image was created. “Manual” Images can be created at any time. “Automatic” Images are created automatically from a deleted Linode. |
updated | string<date-time> When this Image was last updated. |
vendor Nullable | string The upstream distribution vendor. |
errors | array
of objects
|
Image Update
Updates a private Image that you have permission to read_write
.
Authorizations
personalAccessToken | |
oauth | images:read_write |
Path Parameters
imageId | string RequiredID of the Image to look up. |
Request Samples
curl -H "Content-Type: application/json" \
-H "Authorization: Bearer $TOKEN" \
-X PUT -d '{
"label": "My gold-master image",
"description": "The detailed description of my Image."
}' \
https://api.linode.com/v4/images/private/12345
linode-cli images update private/12345 \
--label "My gold-master image" \
--description "The detailed description \
of my Image."
Request Body Schema
description Nullable | string
1..65000
charactersA detailed description of this Image. |
label | string A short description of the Image. |
Response Samples
{
"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
capabilities | array
of strings A list containing the following possible capabilities of this Image:
|
created | string<date-time> When this Image was created. |
created_by | string The name of the User who created this Image, or “linode” for public Images. |
deprecated | boolean Whether or not this Image is deprecated. Will only be true for deprecated public Images. |
description Nullable | string
1..65000
charactersA detailed description of this Image. |
eol Nullable | string<date-time> The date of the public Image’s planned end of life. |
expiry Nullable | string<date-time> Only Images created automatically from a deleted Linode (type=automatic) will expire. |
id | string The unique ID of this Image. |
is_public | boolean True if the Image is a public distribution image. False if Image is private Account-specific Image. |
label | string A short description of the Image. |
size | integer The minimum size this Image needs to deploy. Size is in MB. |
status | string Enum:
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. |
type | string Enum:
manual
automatic How the Image was created. “Manual” Images can be created at any time. “Automatic” Images are created automatically from a deleted Linode. |
updated | string<date-time> When this Image was last updated. |
vendor Nullable | string The upstream distribution vendor. |
errors | array
of objects
|