Skip to content

Download an ISO image from a URL

POST /api/v2/vps/{id}/iso/actions/from-url

Downloads an ISO image from a public HTTP or HTTPS URL so you can mount it on the VPS. The download runs as a job. Follow it with operation.pollUrl (see Jobs). When it is done, the image is listed in available[] on GET /api/v2/vps/{id}/iso. The URL must be a direct link on a public host. Links that redirect or contain a username or password are rejected. Files larger than 20 GB are rejected when the host reports the size.

Authentication: An API key with the scopes write:vm and write:storage and vm:write. About keys and scopes

Request

Path parameters

idstringrequired
The VPS ID (vps_…).

Body

urlstringrequired
Direct HTTP or HTTPS link to the image, at most 500 characters.
filenamestring
File name to save the image as, ending in .iso, at most 100 characters. Leave it out when the URL path ends in a safe .iso file name. Then the API will infer that filename from the URL.
decompressstring
Unpack a compressed image after download: gzip, lzo, zstd or bzip2. Default none. One of none, gzip, lzo, zstd, bzip2.

Example

POST /api/v2/vps/{id}/iso/actions/from-url
curl -X POST "https://cloud.hostup.se/api/v2/vps/vps_01hxa3b4c5d6e7f8g9h0j1k2m3/iso/actions/from-url" \
-H "Authorization: Bearer $HOSTUP_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"url": "https://example.com/downloads/ubuntu-24.04-live-server-amd64.iso",
"filename": "ubuntu-24.04-live-server-amd64.iso",
"decompress": "none"
}'

Responses

200 The file already existed. Nothing was downloaded and there is nothing to poll.

Response 200
{
"operation": {
"status": "completed",
"jobId": "job_01hxa3b4c5d6e7f8g9h0j1k2m3",
"pollUrl": null
}
}
Response fields
operationobject
The finished operation.
statusstring
Always completed. One of completed.
jobIdstring
An operation ID. No job runs for it.
pollUrlstring or null
Always null.

202 The download was queued. Poll operation.pollUrl until the job finishes.

Response 202
{
"operation": {
"status": "queued",
"jobId": "job_01hxa3b4c5d6e7f8g9h0j1k2m3",
"pollUrl": "/api/jobs/job_01hxa3b4c5d6e7f8g9h0j1k2m3"
}
}
Response fields
operationobject
statusstring
Where the job is. A 202 Accepted response only has pending, queued or in_progress. completed and failed appear when you poll pollUrl. They also appear in a 200 OK response when the action finished during the request. One of pending, queued, in_progress, completed, failed.
jobIdstring
pollUrlstring or null
Where to poll the job while it runs. null when status is already completed or failed.

Errors

Errors are Problem Details with a stable code. Branch on the code, not on the text.

400The URL or file name was rejected. detail says why, for example a redirecting link or a file over 20 GB.
401Unauthorized. Authentication is required.
403Forbidden. The caller lacks a required scope or does not own the resource.
404Not found. The resource does not exist or is not owned by the caller; code is vps_not_found.
429Rate limited. Retry after the limit resets. 429 responses include Retry-After seconds plus X-RateLimit-* headers.
500Internal error. Retry later or contact support if the issue persists.
502Upstream failure. A dependent provider request failed; the Problem Details code is upstream_failed. Retry later or contact support if the issue persists.