Skip to content

Set a VPS backup schedule

POST /api/v2/vps/{id}/backup-schedules

Creates the backup schedule of a VPS. A VPS can have one schedule. Sending the same frequency again replaces it. To switch to another frequency, delete the current schedule first. Check actions.canCreate and limits on GET /api/v2/vps/{id}/backup-schedules before you call. hour is in Europe/Stockholm time. The server picks the minute. retentionCount cannot be higher than limits.maxRetention. Plans without backups return 409 product_not_orderable. Backups are offsite, longer-term copies and can take longer to create and restore than snapshots. For a quick rollback point, use POST /api/v2/vps/{id}/snapshot-schedules instead.

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

Request

Path parameters

idstringrequired
The VPS ID (vps_…).

Body

frequencystringrequired
How often to back up: daily, weekly or monthly. One of daily, weekly, monthly.
hourintegerrequired
Hour of the day in Europe/Stockholm time, 0 to 23. 0 to 23.
dayOfWeekinteger
Day of the week, 0 (Sunday) to 6. Required for weekly and not allowed for other frequencies. 0 to 6.
dayOfMonthinteger
Day of the month, 1 to 31. Required for monthly and not allowed for other frequencies. 1 to 31.
retentionCountintegerrequired
How many scheduled backups to keep. At least 1 and at most limits.maxRetention. Each run keeps at most this many scheduled backups. It never keeps more than limits.availableScheduledSlots. At least 1.
enabledbooleanrequired
Whether the schedule runs.
namestring
Label for the schedule. Without one, the 201 response calls it Backup schedule. GET /api/v2/vps/{id}/backup-schedules calls it daily backup, weekly backup or monthly backup. Send a name to get the same label in both.

Example

POST /api/v2/vps/{id}/backup-schedules
curl -X POST "https://cloud.hostup.se/api/v2/vps/vps_01hxa3b4c5d6e7f8g9h0j1k2m3/backup-schedules" \
-H "Authorization: Bearer $HOSTUP_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"frequency": "daily",
"hour": 2,
"retentionCount": 3,
"enabled": true,
"name": "Nightly backup"
}'

Responses

201 The saved schedule.

Response 201
{
"id": "bks_01hxa3b4c5d6e7f8g9h0j1k2m3",
"name": "Nightly backup",
"frequency": "daily",
"time": "02:17",
"daySpecifier": null,
"retentionCount": 3,
"enabled": true,
"lastRun": null,
"nextRun": "2026-04-28T00:17:00.000Z",
"status": null,
"lastRunStatus": null,
"lastRunAt": null
}
Response fields
idstring
Schedule ID (bks_…).
namestring
Label of the schedule.
frequencystring
How often it runs: daily, weekly or monthly. One of daily, weekly, monthly.
timestring or null
Time of day it runs, HH:MM in Europe/Stockholm time.
daySpecifierstring or null
Day of the week (0 is Sunday) for weekly. Day of the month for monthly. Null for daily.
retentionCountinteger
How many scheduled backups it keeps.
enabledboolean
Whether the schedule runs.
lastRunstring or null
When it last ran.
nextRunstring or null
When it runs next.
statusstring or null
Status of the schedule, when one is reported. Read lastRunStatus for the result of its last backup. One of completed, running, queued, failed, cancelled, unknown.
lastRunStatusstring or null
Result of the newest backup this schedule made: completed, failed or queued. Null when it has not run yet. One of completed, running, queued, failed, cancelled, unknown.
lastRunAtstring or null
When the newest backup of this schedule started. Null when it has not run yet.

Errors

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

400The body is invalid. A field that breaks the rules above returns one detail that lists the rules, without errors. A retentionCount above limits.maxRetention returns errors[0].pointer /retentionCount and errors[0].code retention_exceeds_backup_limit, plus limits.
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.
409No schedule can be saved. Branch on code: backup_schedule_limit_reached (another schedule exists or no backup slot is free) or product_not_orderable (the plan has no backups). actions.canCreate and limits in the body say why.
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.