Images

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.

Request Body Schema

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.

description
string

Description for the uploaded Image.

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

Response Samples

{
  "upload_to": "",
  "image": {
    "id": "linode/debian11",
    "label": "Debian 11",
    "created": "2021-08-14T22:44:02",
    "updated": "2021-08-14T22:44:02",
    "created_by": "linode",
    "deprecated": false,
    "description": "Example Image description.",
    "is_public": true,
    "size": 2500,
    "type": "manual",
    "expiry": "",
    "eol": "2026-07-01T04:00:00",
    "vendor": "Debian",
    "status": "available",
    "capabilities": [
      "cloud-init"
    ]
  }
}

Responses

200: Image Upload object including the upload URL and Image object.

upload_to
string

The URL to upload the Image to.

image
object

Image object

id
string

The unique ID of this Image.

label
Filterable
string

A short description of the Image.

created
string

When this Image was created.

updated
string

When this Image was last updated.

created_by
string

The name of the User who created this Image, or "linode" for public Images.

deprecated
Filterable
boolean

Whether or not this Image is deprecated. Will only be true for deprecated public Images.

description
Nullable
string

A detailed description of this Image.

is_public
Filterable
boolean

True if the Image is a public distribution image. False if Image is private Account-specific Image.

size
Filterable
integer

The minimum size this Image needs to deploy. Size is in MB.

type
Filterable
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.

expiry
Nullable
string

Only Images created automatically from a deleted Linode (type=automatic) will expire.

eol
string

The date of the public Image's planned end of life. None for private Images.

vendor
Filterable
string

The upstream distribution vendor. None for private Images.

status
Filterable
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.

capabilities
array

A list containing the following possible capabilities of this Image:

cloud-init: This Image supports cloud-init with Metadata. Only applies to public Images.

default: Error

errors
array of objects
reason
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.

field
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.