API reference
Accounts
Hosting accounts: create, suspend, terminate, change package, limits, owner, password; single sign-on links.
#List accounts
GET/api/v1/accounts
Returns the accounts with filters, sorting and (with ?page=) pagination, plus the list totals.
- Who
- root, reseller (ACL: list-accts)
- API tokens
- admin token area: accounts
- Operation
listAccounts · ky call listAccounts
Parameters
| Name | In |
|---|
dir | query |
over_bandwidth | query |
over_quota | query |
owner | query |
package | query |
page | query |
per_page | query |
q | query |
sort | query |
status | query |
Responses
- 200 OK
Body
- 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
#Create an account
POST/api/v1/accounts
- Who
- root, reseller (ACL: create-acct)
- API tokens
- admin token area: accounts
- Operation
createAccount · ky call createAccount
Request body
| Field | Type |
|---|
cgi | boolean |
contact_email | string |
database_node | string |
domain | string |
ip_id | string |
locale | string |
mail_node | string |
mail_routing | string |
make_reseller | boolean |
owner_id | string |
owns_itself | boolean |
package_id | string |
password | string |
shell | string |
spam_box | boolean |
spam_filter | boolean |
username | string |
Responses
- 202 Accepted (runs in the background)
Body
- 400 Bad Request: validation
- 401 Unauthorized: no session, or an invalid or expired token
- 403 Forbidden: reseller-limit
- 409 Conflict: conflict
- 500 Internal Server Error: internal
#Bandwidth of every account in a month
GET/api/v1/accounts-bandwidth
Returns every account's traffic in ?month=YYYY-MM (default: this month, server time zone).
- Who
- root, reseller (ACL: show-bandwidth or list-accts)
- API tokens
- admin token area: server
- Operation
bandwidthByMonth · ky call bandwidthByMonth
Parameters
Responses
- 200 OK
Body
- 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
#Check a username or domain before creating an account
GET/api/v1/accounts-check
- Who
- root, reseller (ACL: create-acct)
- API tokens
- admin token area: accounts
- Operation
checkAccount · ky call checkAccount
Parameters
| Name | In |
|---|
domain | query |
username | query |
Responses
- 200 OK
Body
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
#List the possible account owners (root and resellers)
GET/api/v1/accounts-owners
- Who
- root
- API tokens
- admin token area: server
- Operation
accountOwners · ky call accountOwners
Responses
- 200 OK
Body
- 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
#Terminate an account
DELETE/api/v1/accounts/{id}
- Who
- root, reseller (ACL: kill-acct)
- API tokens
- admin token area: accounts
- Operation
deleteAccount · ky call deleteAccount
Parameters
| Name | In |
|---|
id | path |
confirm | query |
keep_home | query |
Responses
- 202 Accepted (runs in the background)
Body
- 400 Bad Request: confirmation-required
- 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-terminating, is-reseller
- 500 Internal Server Error: internal
#Get an account
GET/api/v1/accounts/{id}
- Who
- root, reseller (ACL: list-accts or create-user-session); customer
- API tokens
- admin token area: accounts; account token area: account
- Operation
getAccount · ky call getAccount
Parameters
Responses
- 200 OK
Body
| Field | Type |
|---|
bw_exceeded always | boolean |
bw_limit_mb | integer |
bw_used_month_mb always | integer |
cgi always | boolean |
contact_email always | string |
created_at always | integer |
db_count always | integer |
db_prefix always | string |
db_used_bytes always | integer |
default_email_quota_mb | integer |
disk_quota_mb | integer |
disk_used_mb always | integer |
feature_list_id always | string |
home_dir always | string |
id always | string |
inodes_limit | integer |
inodes_used always | integer |
ip_address always | string |
ip_id always | string |
is_reseller always | boolean |
locale always | string |
main_domain always | string |
make_reseller always | boolean |
max_addon | integer |
max_email | integer |
max_email_per_hour | integer |
max_email_quota_mb | integer |
max_ftp | integer |
max_parked | integer |
max_sql | integer |
max_sub | integer |
owner_id always | string |
owner_name always | string |
package_id always | string |
package_name always | string |
php_max_children | integer |
shell always | string |
status always | string |
suspend_locked always | boolean |
suspend_reason always | string |
suspended_at | integer |
suspended_by | string |
theme always | string |
uid always | integer |
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
#Include or exclude the account from backups
PUT/api/v1/accounts/{id}/backup-enabled
- Who
- root
- API tokens
- admin token area: accounts
- Operation
backupAccountToggle · ky call backupAccountToggle
Parameters
Request body
Responses
- 200 OK
Body
- 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
#Bandwidth of the account per day
GET/api/v1/accounts/{id}/bandwidth
Returns the account's traffic per day, domain and protocol for the last ?days= (default 31).
- Who
- root, reseller (ACL: show-bandwidth or list-accts); customer
- API tokens
- admin token area: accounts; account token area: account
- Feature
bandwidth- Operation
accountBandwidth · ky call accountBandwidth
Parameters
Responses
- 200 OK
Body
| Field | Type |
|---|
exceeded | boolean |
from_day | integer |
items | array of StoreBandwidthRow |
limit_mb | integer |
timezone | string |
used_month_mb | 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
- 500 Internal Server Error: internal
#Allow or forbid CGI scripts
PUT/api/v1/accounts/{id}/cgi
- Who
- root, reseller (ACL: edit-account)
- API tokens
- admin token area: accounts
- Operation
setAccountCGI · ky call setAccountCGI
Parameters
Request body
Responses
- 202 Accepted (runs in the background)
Body
- 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 account's main domain
POST/api/v1/accounts/{id}/domain
- Who
- root, reseller (ACL: edit-account)
- API tokens
- admin token area: accounts
- Operation
changeDomain · ky call changeDomain
Parameters
Request body
Responses
- 202 Accepted (runs in the background)
Body
- 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: account-busy
- 500 Internal Server Error: internal
#Preview a main domain change
POST/api/v1/accounts/{id}/domain-plan
- Who
- root, reseller (ACL: edit-account)
- API tokens
- admin token area: accounts
- Operation
domainPlan · ky call domainPlan
Parameters
Request body
Responses
- 200 OK
Body
| Field | Type |
|---|
blockers always | array of string |
from always | string |
ok always | boolean |
renames always | array of StoreDomainRename |
steps always | array of string |
to always | 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
- 500 Internal Server Error: internal
#Change the account's IP address
PUT/api/v1/accounts/{id}/ip
- Who
- root, reseller (ACL: edit-account)
- API tokens
- admin token area: accounts
- Operation
setAccountIP · ky call setAccountIP
Parameters
Request body
Responses
- 202 Accepted (runs in the background)
Body
- 400 Bad Request: validation
- 401 Unauthorized: no session, or an invalid or expired token
- 403 Forbidden: package-privileges
- 404 Not Found: not-found
- 409 Conflict: account-busy, validation
- 500 Internal Server Error: internal
#Override the account's limits
PUT/api/v1/accounts/{id}/limits
Overrides the account's limits (the package stays; the account becomes "customized").
- Who
- root, reseller (ACL: edit-account)
- API tokens
- admin token area: accounts
- Operation
setAccountLimits · ky call setAccountLimits
Parameters
Request body
| Field | Type |
|---|
bw_limit_mb | integer |
disk_quota_mb | integer |
max_addon | integer |
max_email | integer |
max_email_per_hour | integer |
max_email_quota_mb | integer |
max_ftp | integer |
max_parked | integer |
max_sql | integer |
max_sub | integer |
php_max_children | integer |
Responses
- 202 Accepted (runs in the background)
Body
| Field | Type |
|---|
account | StoreAccount |
job_id | string |
warnings | array of map of any |
- 400 Bad Request: validation
- 401 Unauthorized: no session, or an invalid or expired token
- 403 Forbidden: package-privileges, reseller-limit
- 404 Not Found: not-found
- 409 Conflict: account-busy
- 500 Internal Server Error: internal
#Change the account's language
PUT/api/v1/accounts/{id}/locale
- Who
- root, reseller (ACL: edit-account)
- API tokens
- admin token area: accounts
- Operation
setAccountLocale · ky call setAccountLocale
Parameters
Request body
Responses
- 204 Done, no content
- 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
#Open the customer panel as the account
POST/api/v1/accounts/{id}/login-as
Generates a single-use link (60 s) for the admin to open the customer's panel.
- Who
- root, reseller (ACL: create-user-session)
- API tokens
- API tokens can't use this endpoint
- Operation
loginAs · ky call loginAs
Parameters
Responses
- 200 OK
Body
- 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 account's owner
PUT/api/v1/accounts/{id}/owner
- Who
- root
- API tokens
- admin token area: accounts
- Operation
setAccountOwner · ky call setAccountOwner
Parameters
Request body
Responses
- 200 OK
Body
| Field | Type |
|---|
bw_exceeded always | boolean |
bw_limit_mb | integer |
bw_used_month_mb always | integer |
cgi always | boolean |
contact_email always | string |
created_at always | integer |
db_count always | integer |
db_prefix always | string |
db_used_bytes always | integer |
default_email_quota_mb | integer |
disk_quota_mb | integer |
disk_used_mb always | integer |
feature_list_id always | string |
home_dir always | string |
id always | string |
inodes_limit | integer |
inodes_used always | integer |
ip_address always | string |
ip_id always | string |
is_reseller always | boolean |
locale always | string |
main_domain always | string |
make_reseller always | boolean |
max_addon | integer |
max_email | integer |
max_email_per_hour | integer |
max_email_quota_mb | integer |
max_ftp | integer |
max_parked | integer |
max_sql | integer |
max_sub | integer |
owner_id always | string |
owner_name always | string |
package_id always | string |
package_name always | string |
php_max_children | integer |
shell always | string |
status always | string |
suspend_locked always | boolean |
suspend_reason always | string |
suspended_at | integer |
suspended_by | string |
theme always | string |
uid always | integer |
username always | 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
- 500 Internal Server Error: internal
#Move the account to another package
PUT/api/v1/accounts/{id}/package
Moves the account to a package: every limit, the PHP-FPM children and the shell follow it. Going under the current usage needs "force" (nothing is deleted; the account just can't create more).
- Who
- root, reseller (ACL: upgrade-acct)
- API tokens
- admin token area: accounts
- Operation
setAccountPackage · ky call setAccountPackage
Parameters
Request body
| Field | Type |
|---|
force | boolean |
package_id | string |
Responses
- 202 Accepted (runs in the background)
Body
| Field | Type |
|---|
account | StoreAccount |
job_id | string |
warnings | array of map of any |
- 400 Bad Request: validation
- 401 Unauthorized: no session, or an invalid or expired token
- 403 Forbidden: reseller-limit
- 404 Not Found: not-found
- 409 Conflict: account-busy
- 500 Internal Server Error: internal
#Check whether the account fits a package
GET/api/v1/accounts/{id}/package-check
- Who
- root, reseller (ACL: upgrade-acct)
- API tokens
- admin token area: accounts
- Operation
packageCheck · ky call packageCheck
Parameters
| Name | In |
|---|
id | path |
package_id | query |
Responses
- 200 OK
Body
- 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
#Change the account's password
POST/api/v1/accounts/{id}/password
- Who
- root, reseller (ACL: passwd); customer
- API tokens
- admin token area: accounts; account tokens: not allowed
- Operation
acctPassword · ky call acctPassword
Parameters
Request body
| Field | Type |
|---|
current_password | string |
new_password | string |
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
- 429 Too Many Requests: too-many-attempts
- 500 Internal Server Error: internal
#Get the account's preferences
GET/api/v1/accounts/{id}/preferences
- Who
- root, reseller (ACL: create-user-session); customer
- API tokens
- admin token area: accounts; account token area: account
- Operation
acctPreferences · ky call acctPreferences
Parameters
Responses
- 200 OK
Body
| Field | Type |
|---|
locales | array of map of string |
preferences | AcctPrefs |
- 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 account's preferences
PUT/api/v1/accounts/{id}/preferences
- Who
- root, reseller (ACL: create-user-session); customer
- API tokens
- admin token area: accounts; account token area: account
- Operation
acctSavePreferences · ky call acctSavePreferences
Parameters
Request body
| Field | Type |
|---|
contact_email | string |
contact_email2 | string |
locale | string |
notifications | map of boolean |
Responses
- 200 OK
Body
| Field | Type |
|---|
locales | array of map of string |
preferences | AcctPrefs |
- 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
#Change the account's disk quota
PUT/api/v1/accounts/{id}/quota
- Who
- root, reseller (ACL: quota or edit-account)
- API tokens
- admin token area: accounts
- Operation
setAccountQuota · ky call setAccountQuota
Parameters
Request body
| Field | Type |
|---|
disk_quota_mb | integer |
Responses
- 202 Accepted (runs in the background)
Body
| Field | Type |
|---|
account | StoreAccount |
job_id | string |
warnings | array of string |
- 400 Bad Request: validation
- 401 Unauthorized: no session, or an invalid or expired token
- 403 Forbidden: reseller-limit
- 404 Not Found: not-found
- 409 Conflict: account-busy
- 500 Internal Server Error: internal
#Change the account's username
POST/api/v1/accounts/{id}/rename
- Who
- root, reseller (ACL: edit-account)
- API tokens
- admin token area: accounts
- Operation
renameAccount · ky call renameAccount
Parameters
Request body
Responses
- 202 Accepted (runs in the background)
Body
- 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: account-busy, not-active, validation
- 500 Internal Server Error: internal
#Preview a username change
POST/api/v1/accounts/{id}/rename-plan
- Who
- root, reseller (ACL: edit-account)
- API tokens
- admin token area: accounts
- Operation
renamePlan · ky call renamePlan
Parameters
Request body
Responses
- 200 OK
Body
| Field | Type |
|---|
blockers always | array of string |
changes always | array of StoreNameChange |
checks always | array of HostingPlanCheck |
from always | string |
ok always | boolean |
steps always | array of string |
to always | string |
- 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)
- 404 Not Found: not-found
- 500 Internal Server Error: internal
#Repair the account's configuration
POST/api/v1/accounts/{id}/repair
- Who
- root, reseller (ACL: create-user-session); customer
- API tokens
- admin token area: accounts; account token area: account
- Operation
repairAccount · ky call repairAccount
Parameters
Responses
- 202 Accepted (runs in the background)
Body
- 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
#CPU, memory, I/O and process usage of the account
GET/api/v1/accounts/{id}/resource-usage
The account's limits and its CPU/memory/I/O/process samples with faults (limits hit).
- Who
- root, reseller (ACL: list-accts); customer
- API tokens
- admin token area: accounts; account token area: resource-usage
- Feature
resource_usage- Operation
accountResourceUsage · ky call accountResourceUsage
Parameters
Responses
- 200 OK
Body
| Field | Type |
|---|
bucket | string |
faults | object| Field | Type |
|---|
cpu | integer | ep | integer | io | integer | mem | integer | nproc | integer |
|
limits | StoreIsolation |
range | string |
samples | array of StoreUsageSample |
- 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 account's shell access
PUT/api/v1/accounts/{id}/shell
- Who
- root, reseller (ACL: edit-account)
- API tokens
- admin token area: accounts
- Operation
setAccountShell · ky call setAccountShell
Parameters
Request body
Responses
- 202 Accepted (runs in the background)
Body
- 400 Bad Request: validation
- 401 Unauthorized: no session, or an invalid or expired token
- 403 Forbidden: package-privileges
- 404 Not Found: not-found
- 409 Conflict: account-busy
- 500 Internal Server Error: internal
#Create a single sign-on link for the account
POST/api/v1/accounts/{id}/sso
Issues a single-use sign-in link (60 s) for billing systems and other integrations: the customer opens it and lands in their panel (or a reseller in Ky Admin) without a password.
- Who
- root, reseller (ACL: create-user-session)
- API tokens
- admin token area: accounts
- Operation
accountSSO · ky call accountSSO
Parameters
Request body
| Field | Type |
|---|
goto | string |
panel | string |
Responses
- 200 OK
Body
| Field | Type |
|---|
expires_in | integer |
url | 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: not-reseller, suspended
- 422 Unprocessable Entity: invalid-goto, invalid-panel
- 500 Internal Server Error: internal
#Suspend an account
POST/api/v1/accounts/{id}/suspend
- Who
- root, reseller (ACL: suspend-acct)
- API tokens
- admin token area: accounts
- Operation
suspendAccount · ky call suspendAccount
Parameters
Request body
| Field | Type |
|---|
locked | boolean |
reason | string |
Responses
- 202 Accepted (runs in the background)
Body
- 400 Bad Request: validation
- 401 Unauthorized: no session, or an invalid or expired token
- 403 Forbidden: suspension-locked
- 404 Not Found: not-found
- 409 Conflict: account-busy
- 500 Internal Server Error: internal
#Unsuspend an account
POST/api/v1/accounts/{id}/unsuspend
- Who
- root, reseller (ACL: suspend-acct)
- API tokens
- admin token area: accounts
- Operation
unsuspendAccount · ky call unsuspendAccount
Parameters
Responses
- 202 Accepted (runs in the background)
Body
- 401 Unauthorized: no session, or an invalid or expired token
- 403 Forbidden: suspension-locked
- 404 Not Found: not-found
- 409 Conflict: not-suspended
- 500 Internal Server Error: internal
#Usage against the account's limits
GET/api/v1/accounts/{id}/usage
Returns usage against limits for every limited resource (customer Home stats bar).
- Who
- root, reseller (ACL: list-accts); customer
- API tokens
- admin token area: accounts; account token area: usage
- Operation
accountUsage · ky call accountUsage
Parameters
Responses
- 200 OK
Body
| Field | Type |
|---|
db_used_bytes | integer |
default_email_quota_mb | integer |
items | array of UsageItem |
max_email_per_hour | integer |
max_email_quota_mb | integer |
warn_pct | 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
- 500 Internal Server Error: internal
#Terminate several accounts
POST/api/v1/accounts/bulk-terminate
- Who
- root, reseller (ACL: kill-acct)
- API tokens
- admin token area: accounts
- Operation
bulkTerminate · ky call bulkTerminate
Request body
| Field | Type |
|---|
confirm | string |
ids | array of string |
keep_dns | boolean |
keep_home | boolean |
Responses
- 202 Accepted (runs in the background)
Body
- 400 Bad Request: confirmation-required, 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
#Export the account list as CSV
GET/api/v1/accounts/export.csv
Streams the filtered list as CSV (every match, no pagination).
- Who
- root, reseller (ACL: list-accts)
- API tokens
- admin token area: accounts
- Operation
exportAccounts · ky call exportAccounts
Parameters
| Name | In |
|---|
dir | query |
over_bandwidth | query |
over_quota | query |
owner | query |
package | query |
page | query |
per_page | query |
q | query |
sort | query |
status | query |
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)
- 500 Internal Server Error: internal
