API reference

Backups

Scheduled backups, destinations, restores and the customer's own backups.

List the account's backups

GET/api/v1/accounts/{id}/backups

Who: root, reseller (ACL: create-user-session); customer
API tokens: admin token area: accounts; account token area: backups
Feature: backups
Operation: accountBackups · ky call accountBackups

Parameters

Name	In
`id`	path

Responses

200 OK
Body
Field Type
items array of Entry
401 Unauthorized: no session, or an invalid or expired token
403 Forbidden: the caller can't use this (privileges, token scope, feature turned off)
404 Not Found: not-found
409 Conflict: not-ready
500 Internal Server Error: internal

Field	Type
`items`	array of Entry

Download a backup

GET/api/v1/accounts/{id}/backups/{sid}/download

Who: root, reseller (ACL: create-user-session); customer
API tokens: admin token area: accounts; account token area: backups
Feature: backups
Operation: accountBackupDownload · ky call accountBackupDownload

Parameters

Name	In
`id`	path
`sid`	path

Responses

200 OK
400 Bad Request: file-operation
401 Unauthorized: no session, or an invalid or expired token
403 Forbidden: the caller can't use this (privileges, token scope, feature turned off)
404 Not Found: not-found
409 Conflict: not-ready
500 Internal Server Error: internal

Browse the files of a backup

GET/api/v1/accounts/{id}/backups/{sid}/files

Who: root, reseller (ACL: create-user-session); customer
API tokens: admin token area: accounts; account token area: backups
Feature: backups
Operation: accountBackupFiles · ky call accountBackupFiles

Parameters

Name	In
`id`	path
`sid`	path
`path`	query

Responses

200 OK
Body
Field Type
items array of map of any
path string
taken_at integer
400 Bad Request: file-operation
401 Unauthorized: no session, or an invalid or expired token
403 Forbidden: the caller can't use this (privileges, token scope, feature turned off)
404 Not Found: not-found
409 Conflict: not-ready
500 Internal Server Error: internal

Field	Type
`items`	array of map of any
`path`	string
`taken_at`	integer

Restore files from a backup

POST/api/v1/accounts/{id}/backups/{sid}/restore-files

Who: root, reseller (ACL: create-user-session); customer
API tokens: admin token area: accounts; account token area: backups
Feature: backups
Operation: accountBackupRestoreFiles · ky call accountBackupRestoreFiles

Parameters

Name	In
`id`	path
`sid`	path

Request body

Field	Type
`overwrite`	boolean
`path`	string
`to`	string

Responses

202 Accepted (runs in the background)
Body
Field Type
job_id string
400 Bad Request: validation
401 Unauthorized: no session, or an invalid or expired token
403 Forbidden: the caller can't use this (privileges, token scope, feature turned off)
404 Not Found: not-found
409 Conflict: not-ready
500 Internal Server Error: internal

Field	Type
`job_id`	string

Create a full backup of the account

POST/api/v1/accounts/{id}/backups/full

Who: root, reseller (ACL: create-user-session); customer
API tokens: admin token area: accounts; account token area: backups
Feature: backups
Operation: userFullBackup · ky call userFullBackup

Parameters

Name	In
`id`	path

Request body

Field	Type
`destination`	string
`host`	string
`password`	string
`path`	string
`port`	integer
`tls`	string
`user`	string

Responses

202 Accepted (runs in the background)
Body
Field Type
job_id string
400 Bad Request: validation
401 Unauthorized: no session, or an invalid or expired token
403 Forbidden: the caller can't use this (privileges, token scope, feature turned off)
404 Not Found: not-found
409 Conflict: busy, not-ready
500 Internal Server Error: internal

Field	Type
`job_id`	string

Download a database backup

GET/api/v1/accounts/{id}/backups/partial/databases/{db}

Who: root, reseller (ACL: create-user-session); customer
API tokens: admin token area: accounts; account token area: backups
Feature: backups
Operation: partialDB · ky call partialDB

Parameters

Name	In
`id`	path
`db`	path

Responses

200 OK
400 Bad Request: file-operation
401 Unauthorized: no session, or an invalid or expired token
403 Forbidden: the caller can't use this (privileges, token scope, feature turned off)
404 Not Found: not-found
409 Conflict: not-ready
500 Internal Server Error: internal

Download the email filters

GET/api/v1/accounts/{id}/backups/partial/filters

Who: root, reseller (ACL: create-user-session); customer
API tokens: admin token area: accounts; account token area: backups
Feature: backups
Operation: partialFilters · ky call partialFilters

Parameters

Name	In
`id`	path

Responses

200 OK
Body
Field Type
filters always array of HostingExportedFilter
format always string
version always integer
401 Unauthorized: no session, or an invalid or expired token
403 Forbidden: the caller can't use this (privileges, token scope, feature turned off)
404 Not Found: not-found
409 Conflict: not-ready
500 Internal Server Error: internal

Field	Type
`filters` always	array of HostingExportedFilter
`format` always	string
`version` always	integer

Download a domain's forwarders

GET/api/v1/accounts/{id}/backups/partial/forwarders/{did}

Who: root, reseller (ACL: create-user-session); customer
API tokens: admin token area: accounts; account token area: backups
Feature: backups
Operation: partialForwarders · ky call partialForwarders

Parameters

Name	In
`id`	path
`did`	path

Responses

200 OK
401 Unauthorized: no session, or an invalid or expired token
403 Forbidden: the caller can't use this (privileges, token scope, feature turned off)
404 Not Found: not-found
409 Conflict: not-ready
500 Internal Server Error: internal

Download a home directory backup

GET/api/v1/accounts/{id}/backups/partial/home

Who: root, reseller (ACL: create-user-session); customer
API tokens: admin token area: accounts; account token area: backups
Feature: backups
Operation: partialHome · ky call partialHome

Parameters

Name	In
`id`	path

Responses

200 OK
400 Bad Request: file-operation
401 Unauthorized: no session, or an invalid or expired token
403 Forbidden: the caller can't use this (privileges, token scope, feature turned off)
404 Not Found: not-found
409 Conflict: not-ready
500 Internal Server Error: internal

Restore a partial backup

POST/api/v1/accounts/{id}/backups/partial/restore

Takes an uploaded partial backup: kind=home|database (restored by a job) or forwarders|filters (added right away). Multipart fields: kind, file, and database / domain_id / overwrite as needed.

Who: root, reseller (ACL: create-user-session); customer
API tokens: admin token area: accounts; account token area: backups
Feature: backups
Operation: partialRestore · ky call partialRestore

Parameters

Name	In
`id`	path

Responses

200 OK
Body
Field Type
added integer
notes array of string
skipped integer
202 Accepted (runs in the background)
Body
Field Type
job_id string
400 Bad Request: invalid-body, invalid-file, upload, validation
401 Unauthorized: no session, or an invalid or expired token
403 Forbidden: the caller can't use this (privileges, token scope, feature turned off)
404 Not Found: not-found
409 Conflict: not-ready
422 Unprocessable Entity: rejected
500 Internal Server Error: internal

Field	Type
`added`	integer
`notes`	array of string
`skipped`	integer

Field	Type
`job_id`	string

Backup status of every account

GET/api/v1/backup/accounts

Who: root
API tokens: admin token area: server
Operation: backupAccounts · ky call backupAccounts

Responses

200 OK
Body
Field Type
items array of map of any
401 Unauthorized: no session, or an invalid or expired token
403 Forbidden: the caller can't use this (privileges, token scope, feature turned off)
500 Internal Server Error: internal

Field	Type
`items`	array of map of any

Get the backup configuration

GET/api/v1/backup/config

Who: root
API tokens: admin token area: server
Operation: backupConfigGet · ky call backupConfigGet

Responses

200 OK
Body
Field Type
config StoreBackupConfig
disk object
Field Type
free always integer
total always integer
401 Unauthorized: no session, or an invalid or expired token
403 Forbidden: the caller can't use this (privileges, token scope, feature turned off)
500 Internal Server Error: internal

Save the backup configuration

PUT/api/v1/backup/config

Who: root
API tokens: admin token area: server
Operation: backupConfigPut · ky call backupConfigPut

Request body

Field	Type
`backup_dir`	string
`db_mode`	string
`enabled`	boolean
`excludes`	array of string
`include`	StoreBackupInclude
`min_free_pct`	integer
`retain_local`	boolean
`retention`	StoreBackupRetention
`schedule`	StoreBackupSchedule
`strict_retention`	boolean
`type`	string
`updated_at`	integer

Responses

200 OK
Body
Field Type
config StoreBackupConfig
disk object
Field Type
free always integer
total always integer
400 Bad Request: validation
401 Unauthorized: no session, or an invalid or expired token
403 Forbidden: the caller can't use this (privileges, token scope, feature turned off)
500 Internal Server Error: internal

List backup destinations

GET/api/v1/backup/destinations

Who: root
API tokens: admin token area: server
Operation: destList · ky call destList

Responses

200 OK
Body
Field Type
items array of StoreBackupDestination
401 Unauthorized: no session, or an invalid or expired token
403 Forbidden: the caller can't use this (privileges, token scope, feature turned off)
500 Internal Server Error: internal

Field	Type
`items`	array of StoreBackupDestination

Add a backup destination

POST/api/v1/backup/destinations

Who: root
API tokens: admin token area: server
Operation: postBackupDestinations · ky call postBackupDestinations

Request body

Field	Type
`config`	HostingDestConfig
`enabled`	boolean
`name`	string
`new_key`	boolean
`secret`	string
`timeout_s`	integer
`type`	string

Responses

200 OK
400 Bad Request: validation
401 Unauthorized: no session, or an invalid or expired token
403 Forbidden: the caller can't use this (privileges, token scope, feature turned off)
404 Not Found: not-found
500 Internal Server Error: internal

Delete a backup destination

DELETE/api/v1/backup/destinations/{did}

Who: root
API tokens: admin token area: server
Operation: destDelete · ky call destDelete

Parameters

Name	In
`did`	path

Responses

204 Done, no content
401 Unauthorized: no session, or an invalid or expired token
403 Forbidden: the caller can't use this (privileges, token scope, feature turned off)
500 Internal Server Error: internal

Update a backup destination

PUT/api/v1/backup/destinations/{did}

Who: root
API tokens: admin token area: server
Operation: putBackupDestinationsDid · ky call putBackupDestinationsDid

Parameters

Name	In
`did`	path

Request body

Field	Type
`config`	HostingDestConfig
`enabled`	boolean
`name`	string
`new_key`	boolean
`secret`	string
`timeout_s`	integer
`type`	string

Responses

200 OK
400 Bad Request: validation
401 Unauthorized: no session, or an invalid or expired token
403 Forbidden: the caller can't use this (privileges, token scope, feature turned off)
404 Not Found: not-found
500 Internal Server Error: internal

Test a backup destination

POST/api/v1/backup/destinations/{did}/validate

Who: root
API tokens: admin token area: server
Operation: destValidate · ky call destValidate

Parameters

Name	In
`did`	path

Responses

200 OK
Body
Field Type
destination StoreBackupDestination
ok boolean
401 Unauthorized: no session, or an invalid or expired token
403 Forbidden: the caller can't use this (privileges, token scope, feature turned off)
404 Not Found: not-found
500 Internal Server Error: internal

Field	Type
`destination`	StoreBackupDestination
`ok`	boolean

Run the backup now

POST/api/v1/backup/run

Who: root
API tokens: admin token area: server
Operation: backupRunNow · ky call backupRunNow

Request body

Field	Type
`account_ids`	array of string

Responses

202 Accepted (runs in the background)
Body
Field Type
job_id string
400 Bad Request: not-found
401 Unauthorized: no session, or an invalid or expired token
403 Forbidden: the caller can't use this (privileges, token scope, feature turned off)
409 Conflict: busy
500 Internal Server Error: internal

Field	Type
`job_id`	string

List backup runs

GET/api/v1/backup/runs

Who: root
API tokens: admin token area: server
Operation: backupRuns · ky call backupRuns

Responses

200 OK
Body
Field Type
items array of StoreBackupRun
401 Unauthorized: no session, or an invalid or expired token
403 Forbidden: the caller can't use this (privileges, token scope, feature turned off)
500 Internal Server Error: internal

Field	Type
`items`	array of StoreBackupRun

List backups by day or account

GET/api/v1/backup/snapshots

By day (?date=2026-10-15, server time) or by account (?username=), for the restore screens.

Who: root
API tokens: admin token area: server
Operation: backupSnapshots · ky call backupSnapshots

Parameters

Name	In
`date`	query
`username`	query

Responses

200 OK
Body
Field Type
dates array of string
items array of StoreBackupSnapshot
timezone string
400 Bad Request: invalid-date
401 Unauthorized: no session, or an invalid or expired token
403 Forbidden: the caller can't use this (privileges, token scope, feature turned off)
500 Internal Server Error: internal

Field	Type
`dates`	array of string
`items`	array of StoreBackupSnapshot
`timezone`	string

List restores

GET/api/v1/restores

Who: root
API tokens: admin token area: server
Operation: restoreList · ky call restoreList

Responses

200 OK
Body
Field Type
items array of StoreRestoreJob
401 Unauthorized: no session, or an invalid or expired token
403 Forbidden: the caller can't use this (privileges, token scope, feature turned off)
500 Internal Server Error: internal

Field	Type
`items`	array of StoreRestoreJob

Restore accounts from a backup

POST/api/v1/restores

Who: root
API tokens: admin token area: server
Operation: restoreCreate · ky call restoreCreate

Request body

Field	Type
`options`	HostingRestoreOptions
`snapshot_ids`	array of string

Responses

202 Accepted (runs in the background)
Body
Field Type
items array of map of string
400 Bad Request: not-found, validation
401 Unauthorized: no session, or an invalid or expired token
403 Forbidden: the caller can't use this (privileges, token scope, feature turned off)
500 Internal Server Error: internal

Field	Type
`items`	array of map of string

Get a restore

GET/api/v1/restores/{rid}

Who: root
API tokens: admin token area: server
Operation: restoreGet · ky call restoreGet

Parameters

Name	In
`rid`	path

Responses

200 OK

Body

Field	Type
`account_id`	string
`created_at` always	integer
`created_by` always	string
`finished_at`	integer
`id` always	string
`job_id`	string
`mode` always	string
`progress` always	integer
`snapshot_id`	string
`source` always	string
`started_at`	integer
`status` always	string
`target_username` always	string

401 Unauthorized: no session, or an invalid or expired token
403 Forbidden: the caller can't use this (privileges, token scope, feature turned off)
404 Not Found: not-found
500 Internal Server Error: internal

Backups

#List the account's backups

Parameters

Responses

#Download a backup

Parameters

Responses

#Browse the files of a backup

Parameters

Responses

#Restore files from a backup

Parameters

Request body

Responses

#Create a full backup of the account

Parameters

Request body

Responses

#Download a database backup

Parameters

Responses

#Download the email filters

Parameters

Responses

#Download a domain's forwarders

Parameters

Responses

#Download a home directory backup

Parameters

Responses

#Restore a partial backup

Parameters

Responses

#Backup status of every account

Responses

#Get the backup configuration

Responses

#Save the backup configuration

Request body

Responses

#List backup destinations

Responses

#Add a backup destination

Request body

Responses

#Delete a backup destination

Parameters

Responses

#Update a backup destination

Parameters

Request body

Responses

#Test a backup destination

Parameters

Responses

#Run the backup now

Request body

Responses

#List backup runs

Responses

#List backups by day or account

Parameters

Responses

#List restores

Responses

#Restore accounts from a backup

Request body

Responses

#Get a restore

Parameters

Responses

List the account's backups

Download a backup

Browse the files of a backup

Restore files from a backup

Create a full backup of the account

Download a database backup

Download the email filters

Download a domain's forwarders

Download a home directory backup

Restore a partial backup

Backup status of every account

Get the backup configuration

Save the backup configuration

List backup destinations

Add a backup destination

Delete a backup destination

Update a backup destination

Test a backup destination

Run the backup now

List backup runs

List backups by day or account

List restores

Restore accounts from a backup

Get a restore