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
idstringrequiredThe VPS ID (
vps_…).Body
urlstringrequiredDirect HTTP or HTTPS link to the image, at most 500 characters.
filenamestringFile 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.decompressstringUnpack a compressed image after download:
gzip, lzo, zstd or bzip2. Default none. One of none, gzip, lzo, zstd, bzip2.Example
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.
{ "operation": { "status": "completed", "jobId": "job_01hxa3b4c5d6e7f8g9h0j1k2m3", "pollUrl": null }}Response fields
operationobjectThe finished operation.
statusstringAlways
completed. One of completed.jobIdstringAn operation ID. No job runs for it.
pollUrlstring or nullAlways null.
202 The download was queued. Poll operation.pollUrl until the job finishes.
{ "operation": { "status": "queued", "jobId": "job_01hxa3b4c5d6e7f8g9h0j1k2m3", "pollUrl": "/api/jobs/job_01hxa3b4c5d6e7f8g9h0j1k2m3" }}Response fields
operationobjectstatusstringWhere 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.jobIdstringpollUrlstring or nullWhere 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.
| 400 | The URL or file name was rejected. detail says why, for example a redirecting link or a file over 20 GB. |
| 401 | Unauthorized. Authentication is required. |
| 403 | Forbidden. The caller lacks a required scope or does not own the resource. |
| 404 | Not found. The resource does not exist or is not owned by the caller; code is vps_not_found. |
| 429 | Rate limited. Retry after the limit resets. 429 responses include Retry-After seconds plus X-RateLimit-* headers. |
| 500 | Internal error. Retry later or contact support if the issue persists. |
| 502 | Upstream failure. A dependent provider request failed; the Problem Details code is upstream_failed. Retry later or contact support if the issue persists. |