API reference

Server

Server status, services, processes, settings, hostname, updates.

Get the defaults for new accounts

GET/api/v1/server/account-settings

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

Responses

200 OK
Body
Field Type
default_bandwidth_page string
default_suspended_page string
settings HostingAccountSettings
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
`default_bandwidth_page`	string
`default_suspended_page`	string
`settings`	HostingAccountSettings

Save the defaults for new accounts

PUT/api/v1/server/account-settings

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

Request body

Field	Type
`bandwidth_exceeded_action`	string
`bandwidth_page_html`	string
`suspended_page_html`	string

Responses

200 OK
Body
Field Type
job_id string
settings HostingAccountSettings
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

Field	Type
`job_id`	string
`settings`	HostingAccountSettings

Web server status

GET/api/v1/server/apache

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

Responses

200 OK
Body
map of any
400 Bad Request: rejected
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

Get the basic setup (contact, nameservers)

GET/api/v1/server/basic

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

Responses

200 OK
Body
Field Type
contact_email string
contact_email2 string
default_home_root string
hostname string
main_ipv4 string
nameservers array of string
shared_ip string
shared_ip_id 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)
500 Internal Server Error: internal

Save the basic setup

PUT/api/v1/server/basic

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

Request body

Field	Type
`contact_email`	string
`contact_email2`	string
`default_home_root`	string
`nameservers`	array of string

Responses

200 OK
Body
Field Type
contact_email string
contact_email2 string
default_home_root string
hostname string
main_ipv4 string
nameservers array of string
shared_ip string
shared_ip_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)
500 Internal Server Error: internal

Database server overview

GET/api/v1/server/databases

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

Parameters

Name	In
`server`	query

Responses

200 OK
Body
Field Type
databases array of DbRow
users array of UserRow
version string
400 Bad Request: rejected, wrong-server
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
`databases`	array of DbRow
`users`	array of UserRow
`version`	string

List database processes

GET/api/v1/server/databases/processes

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

Parameters

Name	In
`server`	query

Responses

200 OK
Body
map of any
400 Bad Request: rejected, wrong-server
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

Kill a database process

POST/api/v1/server/databases/processes/{pid}/kill

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

Parameters

Name	In
`pid`	path
`server`	query

Request body

Field	Type
`query_only`	boolean

Responses

204 Done, no content
400 Bad Request: rejected, validation, wrong-server
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

Database root access status

GET/api/v1/server/databases/root

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

Parameters

Name	In
`server`	query

Responses

200 OK
Body
map of any
400 Bad Request: rejected, wrong-server
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

Repair database root access

POST/api/v1/server/databases/root/repair

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

Parameters

Name	In
`server`	query

Responses

200 OK
Body
map of any
400 Bad Request: rejected, wrong-server
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

Disk I/O per device

GET/api/v1/server/disk-io

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

Parameters

Name	In
`server`	query

Responses

200 OK
Body
map of any
400 Bad Request: rejected, wrong-server
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

Hardware (CPU, memory, disks)

GET/api/v1/server/hardware

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

Parameters

Name	In
`server`	query

Responses

200 OK
Body
map of any
400 Bad Request: rejected, wrong-server
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

Change the server's hostname

PUT/api/v1/server/hostname

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

Request body

Field	Type
`hostname`	string

Responses

200 OK
Body
Field Type
certificate_job_id string
hostname string
message string
400 Bad Request: rejected, 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)
409 Conflict: validation
500 Internal Server Error: internal

Field	Type
`certificate_job_id`	string
`hostname`	string
`message`	string

Count the recipients of a message to all users

GET/api/v1/server/mass-mail

How many addresses Email All Users (or ?resellers=1) reaches.

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

Parameters

Name	In
`resellers`	query

Responses

200 OK
Body
Field Type
default_from string
recipients 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

Field	Type
`default_from`	string
`recipients`	integer

Email all users or resellers

POST/api/v1/server/mass-mail

Email All Users / Email All Resellers (a task: one message per address).

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

Request body

Field	Type
`body`	string
`from_email`	string
`from_name`	string
`hostname`	string
`reseller_id`	string
`resellers`	boolean
`subject`	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)
500 Internal Server Error: internal

Field	Type
`job_id`	string

List processes

GET/api/v1/server/processes

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

Parameters

Name	In
`server`	query

Responses

200 OK
Body
Field Type
items array of AgentprotoProcess
400 Bad Request: rejected, wrong-server
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
`items`	array of AgentprotoProcess

Kill a process

POST/api/v1/server/processes/{pid}/kill

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

Parameters

Name	In
`pid`	path
`server`	query

Request body

Field	Type
`signal`	string

Responses

204 Done, no content
400 Bad Request: rejected, validation, wrong-server
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

Kill every process of a user

POST/api/v1/server/processes/kill-user

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

Request body

Field	Type
`signal`	string
`user`	string

Responses

200 OK
Body
map of any
400 Bad Request: rejected, 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

Reboot the server

POST/api/v1/server/reboot

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

Parameters

Name	In
`server`	query

Request body

Field	Type
`confirm`	string
`mode`	string

Responses

202 Accepted (runs in the background)
Body
Field Type
message string
400 Bad Request: confirmation-required, rejected, wrong-server
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
`message`	string

Get the DNS resolvers

GET/api/v1/server/resolvers

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

Parameters

Name	In
`server`	query

Responses

200 OK
Body
map of any
400 Bad Request: rejected, wrong-server
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

Save the DNS resolvers

PUT/api/v1/server/resolvers

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

Parameters

Name	In
`server`	query

Request body

Field	Type
`resolvers`	array of string

Responses

200 OK
Body
map of any
400 Bad Request: rejected, wrong-server
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

Resource usage of every account

GET/api/v1/server/resource-usage

Every account's last-24h use and faults, heaviest CPU first (admin overview).

Who: root, reseller (ACL: list-accts)
API tokens: admin token area: server
Operation: serverResourceUsage · ky call serverResourceUsage

Responses

200 OK
Body
Field Type
items array of map of any
range 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)
500 Internal Server Error: internal

Field	Type
`items`	array of map of any
`range`	string

Change the system root password

POST/api/v1/server/root-password

Who: root
API tokens: API tokens can't use this endpoint
Operation: adminRootPassword · ky call adminRootPassword

Parameters

Name	In
`server`	query

Request body

Field	Type
`confirm`	string
`password`	string

Responses

204 Done, no content
400 Bad Request: rejected, validation, wrong-server
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

List services

GET/api/v1/server/services

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

Parameters

Name	In
`server`	query

Responses

200 OK
Body
Field Type
items array of ServiceView
monitor boolean
400 Bad Request: rejected, wrong-server
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
`items`	array of ServiceView
`monitor`	boolean

Start, stop or restart a service

POST/api/v1/server/services/{name}/{action}

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

Parameters

Name	In
`name`	path
`action`	path
`server`	query

Responses

200 OK

Body

Field	Type
`active` always	string
`enabled` always	boolean
`failed`	array of string
`group`	string
`installed` always	boolean
`label`	string
`main_pid` always	integer
`memory_bytes` always	integer
`name`	string
`protected`	boolean
`restarts` always	integer
`since`	integer
`sub` always	string
`unit`	string

400 Bad Request: rejected, wrong-server
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

Monitor a service or stop monitoring it

PUT/api/v1/server/services/{name}/monitor

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

Parameters

Name	In
`name`	path

Request body

Field	Type
`enabled`	boolean

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

Get the server settings

GET/api/v1/server/settings

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

Responses

200 OK
Body
Field Type
mail GlobalcfgMail
smarthost_password_set always boolean
web GlobalcfgWeb
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 server settings

PUT/api/v1/server/settings

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

Request body

Field	Type
`mail`	GlobalcfgMail
`smarthost_password`	string
`smarthost_password_set`	boolean
`web`	GlobalcfgWeb

Responses

200 OK
Body
Field Type
mail GlobalcfgMail
smarthost_password_set always boolean
web GlobalcfgWeb
400 Bad Request: rejected, 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

Server status (load, memory, disks, services)

GET/api/v1/server/status

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

Parameters

Name	In
`server`	query

Responses

200 OK

Body

Field	Type
`agent_version`	string
`cgroup_v2`	boolean
`cpu_model` always	string
`cpus`	integer
`disks` always	array of AgentprotoDiskUsage
`hostname`	string
`kernel`	string
`load1` always	number
`load15` always	number
`load5` always	number
`mem_available_bytes` always	integer
`mem_total_bytes`	integer
`os_id`	string
`os_pretty_name`	string
`os_version`	string
`selinux`	string
`swap_free_bytes` always	integer
`swap_total_bytes` always	integer
`uptime_seconds` always	integer
`virtualization` always	string

400 Bad Request: rejected, wrong-server
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

List tweak settings

GET/api/v1/server/tweak-settings

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

Parameters

Name	In
`category`	query
`q`	query

Responses

200 OK
Body
Field Type
categories array of SettingsCategory
items array of TweakItem
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
`categories`	array of SettingsCategory
`items`	array of TweakItem

Save tweak settings

PUT/api/v1/server/tweak-settings

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

Parameters

Name	In
`category`	query
`q`	query

Request body

Field	Type
`values`	map of any

Responses

200 OK
Body
Field Type
categories array of SettingsCategory
items array of TweakItem
400 Bad Request: rejected, 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

Reset a tweak setting to its default

DELETE/api/v1/server/tweak-settings/{key}

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

Parameters

Name	In
`key`	path

Responses

204 Done, no content
400 Bad Request: rejected, 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

Panel update status

GET/api/v1/server/updates

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

Responses

200 OK

Body

Field	Type
`applying`	string
`available`	boolean
`config`	UpdateConfig
`current_build`	integer
`current_version`	string
`last_check_at`	integer
`last_check_error`	string
`last_result`	UpdateResult
`latest`	UpdateManifest
`nodes` always	array of NodeVersion

401 Unauthorized: no session, or an invalid or expired token
403 Forbidden: the caller can't use this (privileges, token scope, feature turned off)
503 Service Unavailable: updates-off

Install the available panel update

POST/api/v1/server/updates/apply

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

Responses

202 Accepted (runs in the background)
Body
Field Type
message string
version 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)
409 Conflict: up-to-date
502 Bad Gateway: update-failed
503 Service Unavailable: updates-off

Change the update channel

PUT/api/v1/server/updates/channel

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

Request body

Field	Type
`auto`	boolean
`channel`	string

Responses

200 OK

Body

Field	Type
`applying`	string
`available`	boolean
`config`	UpdateConfig
`current_build`	integer
`current_version`	string
`last_check_at`	integer
`last_check_error`	string
`last_result`	UpdateResult
`latest`	UpdateManifest
`nodes` always	array of NodeVersion

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)
502 Bad Gateway: nodes-unreachable
503 Service Unavailable: updates-off

Check for panel updates now

POST/api/v1/server/updates/check

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

Responses

200 OK

Body

Field	Type
`applying`	string
`available`	boolean
`config`	UpdateConfig
`current_build`	integer
`current_version`	string
`last_check_at`	integer
`last_check_error`	string
`last_result`	UpdateResult
`latest`	UpdateManifest
`nodes` always	array of NodeVersion

401 Unauthorized: no session, or an invalid or expired token
403 Forbidden: the caller can't use this (privileges, token scope, feature turned off)
502 Bad Gateway: update-check-failed
503 Service Unavailable: updates-off

Operating system update settings and status

GET/api/v1/server/updates/os

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

Responses

200 OK
Body
Field Type
hour always integer
running always boolean
servers always array of HostingOSUpdateServer
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 operating system update settings

PUT/api/v1/server/updates/os

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

Request body

Field	Type
`enabled`	boolean

Responses

200 OK
Body
Field Type
hour always integer
running always boolean
servers always array of HostingOSUpdateServer
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
502 Bad Gateway: nodes-unreachable

Update the operating system now

POST/api/v1/server/updates/os/run

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

Parameters

Name	In
`server`	query

Responses

202 Accepted (runs in the background)
Body
Field Type
job_id 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
409 Conflict: already-running
500 Internal Server Error: internal

First-run setup status

GET/api/v1/setup

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

Responses

200 OK

Body

Field	Type
`completed` always	boolean
`contact_email` always	string
`hostname` always	string
`license_status` always	string
`main_ipv4` always	string
`nameservers` always	array of string
`terms_accepted` always	boolean
`trial_ends_at`	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

Finish the first-run setup

POST/api/v1/setup

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

Request body

Field	Type
`accept_terms`	boolean
`contact_email`	string
`nameservers`	array of string

Responses

200 OK
Body
Field Type
setup StoreSetupState
warnings map of 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)
500 Internal Server Error: internal

Field	Type
`mail`	GlobalcfgMail
`smarthost_password_set` always	boolean
`web`	GlobalcfgWeb

Field	Type
`hour` always	integer
`running` always	boolean
`servers` always	array of HostingOSUpdateServer

Server

#Get the defaults for new accounts

Responses

#Save the defaults for new accounts

Request body

Responses

#Web server status

Responses

#Get the basic setup (contact, nameservers)

Responses

#Save the basic setup

Request body

Responses

#Database server overview

Parameters

Responses

#List database processes

Parameters

Responses

#Kill a database process

Parameters

Request body

Responses

#Database root access status

Parameters

Responses

#Repair database root access

Parameters

Responses

#Disk I/O per device

Parameters

Responses

#Hardware (CPU, memory, disks)

Parameters

Responses

#Change the server's hostname

Request body

Responses

#Count the recipients of a message to all users

Parameters

Responses

#Email all users or resellers

Request body

Responses

#List processes

Parameters

Responses

#Kill a process

Parameters

Request body

Responses

#Kill every process of a user

Request body

Responses

#Reboot the server

Parameters

Request body

Responses

#Get the DNS resolvers

Parameters

Responses

#Save the DNS resolvers

Parameters

Request body

Responses

#Resource usage of every account

Responses

#Change the system root password

Parameters

Request body

Responses

#List services

Parameters

Responses

#Start, stop or restart a service

Parameters

Responses

#Monitor a service or stop monitoring it

Parameters

Request body

Get the defaults for new accounts

Save the defaults for new accounts

Web server status

Get the basic setup (contact, nameservers)

Save the basic setup

Database server overview

List database processes

Kill a database process

Database root access status

Repair database root access

Disk I/O per device

Hardware (CPU, memory, disks)

Change the server's hostname

Count the recipients of a message to all users

Email all users or resellers

List processes

Kill a process

Kill every process of a user

Reboot the server

Get the DNS resolvers

Save the DNS resolvers

Resource usage of every account

Change the system root password

List services

Start, stop or restart a service

Monitor a service or stop monitoring it

Get the server settings

Save the server settings

Server status (load, memory, disks, services)

List tweak settings

Save tweak settings

Reset a tweak setting to its default

Panel update status

Install the available panel update

Change the update channel

Check for panel updates now

Operating system update settings and status

Save the operating system update settings

Update the operating system now

First-run setup status

Finish the first-run setup