| Current File : //home/keyhelp/www/keyhelp/api/openapi.yml |
openapi: 3.1.0
info:
title: KeyHelp RESTful API
version: '2.12'
description: >
Provides an interface to a server managed by the KeyHelp server administration tool.
There latest version of this documentation is available <a href="https://app.swaggerhub.com/apis-docs/keyhelp/api/" target="_blank">here</a>.
## URL
* To communicate with the API, you need to call a specific URL which looks like the this:<br>
```
https://<hostname>/api/v2/<API endpoint>
```
```
https://<IP address>/api/v2/<API endpoint>
```
* Have a look below to see all available API endoints.
## Authentication
* You need to define API keys inside of the KeyHelp user interface (*Admin area* -> *Configuration* -> *API*).<br>
Each API key should be restricted to certain IP / IP range.
* Pass the API key with each request using the `X-API-Key` header field.
## Request format
* Some requests require you to send data inside of the request body.<br>
These data must be sent as `application/json`.
## Response format
* Use the `ACCEPT` header field to specify your desired response mime type.
* The following response formats are supported:
- `application/json` (default)
- `application/xml`
- `text/yaml`
## Hints
* The API is not enabled by default. You first have to turn it on via KeyHelp user interface.<br>
(*Admin area* -> *Configuration* -> *API*)
* You can define how the API should react in certain cases, for this purpose you might want to have a look at the API options.<br>
(*Admin area* -> *Configuration* -> *API* -> *Options*)
* You can turn on the `password_hash` field in API settings, and so read and set the password hash of a given element.<br>
When using this field, make sure that you always use the same hash algorithm that KeyHelp uses, otherwise full functionality can not be guaranteed. If using the `password_hash` field in `[POST/PUT] /clients/` the additional `password_hash_os` field is required.
* KeyHelp performs a webserver reload every time it is necessary. This can either be triggered by your customers using the KeyHelp UI or a previous API request. Your API client will receive a 500/503 error if it sends the request right in the moment of the reload. You have to ensure, your API client can handle such situations, for example by sending the request again after a few seconds.
* Some object schemas contain a read-only "status" field. The meaning of these values is as follows:<br>
0 = "unknown", 1 = "okay", 2 = "error", 3 = "config_new", 4 = "config_update"
## Shorthand byte values
* When specifying byte values, you can also use a shorthand notation.
* Available options are: K (kilobyte), M (megabyte), G (gigabyte), T (terabyte), P (petabyte)
* One kilobyte is described as 1024 byte, 1M equals to 1048576 bytes.
* Do not use decimals, only integers!
<br>
## HTTP status code summary
| Code | Description |
| --- | --- |
| **200 - OK** | Everything worked as expected. |
| **201 - Created** | The ressource was successfully created. |
| **204 - No Content** | The response does not contain any data. Used on delete operations. |
| **400 - Bad Request** | The request was unacceptable, due to an malformed request, invalid parameter value or a missing required parameter. |
| **401 - Unauthorized** | Invalid API key provided |
| **403 - Forbidden** | API access is denied. |
| **404 - Not Found** | The ressouce was not found / The requested endpoint was not found. |
| **405 - Method Not Allowed** | The HTTP method for the requested endpoint is not allowed. |
| **406 - Not Acceptable** | Invalid Accept header value. Mime type not supported. |
| **5xx - Server error** | Something went wrong on KeyHelp's end. |
<br>
## API version upgrade guide
#### Breaking changes from `v1` to `v2`
1) `[GET] /certificates/`: Output format changed for field `components`.
2) `[PUT/POST] /certificates/`: Certificate components are now specified within the `components` field.
<br>
contact:
name: Alexander Mahr (KeyHelp Developer)
email: info@keyhelp.de
url: https://www.keyhelp.de
servers:
- url: https://{host}/api/v2
description: The URL to your KeyHelp server API.
variables:
host:
default: keyhelp.example.com
description: The servers host name.
security:
- ApiKeyAuth: []
tags:
- name: Server
description: Server endpoint.
- name: Login
description: Login endpoint.
- name: Admins
description: Admins endpoint.
- name: Clients
description: Clients endpoint.
- name: Hosting plans
description: Hosting plans endpoint.
- name: Domains
description: Domains endpoint.
- name: DNS
description: DNS endpoint.
- name: Certificates
description: Certificates endpoint.
- name: Emails
description: Emails endpoint.
- name: Databases
description: Databases endpoint.
- name: FTP users
description: FTP users endpoint.
- name: Scheduled tasks
description: Scheduled tasks endpoint.
- name: Directory protections
description: Directory protections endpoint.
paths:
/server:
get:
tags:
- Server
summary: Returning server information.
description: |
Returns various server information.
If performance is a concern, you can use the query parameters, to query only for the information you need.
parameters:
- $ref: '#/components/parameters/server-meta'
- $ref: '#/components/parameters/server-operating-system'
- $ref: '#/components/parameters/server-utilization'
- $ref: '#/components/parameters/server-resources'
- $ref: '#/components/parameters/server-components'
- $ref: '#/components/parameters/server-additional-php-interpreters'
- $ref: '#/components/parameters/server-ports'
responses:
'200':
$ref: '#/components/responses/server'
'401':
$ref: '#/components/responses/401-unauthorized'
/ping:
get:
tags:
- Server
summary: Returning pong.
description: |
Returns "pong".
Can be used to check API or server availability.
responses:
'200':
$ref: '#/components/responses/ping'
'401':
$ref: '#/components/responses/401-unauthorized'
/login/{id}:
parameters:
- $ref: '#/components/parameters/client-id'
get:
tags:
- Login
summary: Generates a login URL for a particular user.
description: >
Generates a login URL that allows to log in to a user account by calling the returned URL.
Security notes:<br>
The generated URL has a validity period of 60 minutes.<br>
The login URL is protected by a brute force protection.
responses:
'200':
$ref: '#/components/responses/login-url'
'401':
$ref: '#/components/responses/401-unauthorized'
/login/name/{name}:
parameters:
- $ref: '#/components/parameters/client-name'
get:
tags:
- Login
summary: Generates a login URL for a particular user.
description: >
Generates a login URL that allows to log in to a user account by calling the returned URL.
Security notes:<br>
The generated URL has a validity period of 60 minutes.<br>
The login URL is protected by a brute force protection.
responses:
'200':
$ref: '#/components/responses/login-url'
'401':
$ref: '#/components/responses/401-unauthorized'
/admins:
get:
tags:
- Admins
summary: Listing all admins.
description: |
Returns a list of all admin accounts on the server.
You can use the following sort parameter values to sort the results.
* id (default)
* username
parameters:
- $ref: '#/components/parameters/admins-sort'
- $ref: '#/components/parameters/order'
responses:
'200':
$ref: '#/components/responses/admin-array'
'401':
$ref: '#/components/responses/401-unauthorized'
post:
tags:
- Admins
summary: Creating a new admin.
description: >
Creates a new admin account.
If the following properties are empty / not set, they are auto-generated:
* password
If the following properties are auto-generated, they are part of the response:
* password
requestBody:
$ref: '#/components/requestBodies/admin-post'
responses:
'201':
$ref: '#/components/responses/201-created'
'400':
$ref: '#/components/responses/400-bad-request'
'401':
$ref: '#/components/responses/401-unauthorized'
/admins/{id}:
parameters:
- $ref: '#/components/parameters/admin-id'
get:
tags:
- Admins
summary: Returning a single admin.
description: |
Returns account details of a single admin determined by its ID.
responses:
'200':
$ref: '#/components/responses/admin'
'401':
$ref: '#/components/responses/401-unauthorized'
'404':
$ref: '#/components/responses/404-not-found'
put:
tags:
- Admins
summary: Updating admin.
description: >
Updates an admin account.
Specify only the fields, you want to update.
If the following properties are part of the request but empty / null, they are auto-generated:
* password
If the following properties are auto-generated, they are part of the response:
* password
requestBody:
$ref: '#/components/requestBodies/admin-put'
responses:
'200':
$ref: '#/components/responses/200-ok-updated'
'400':
$ref: '#/components/responses/400-bad-request'
'401':
$ref: '#/components/responses/401-unauthorized'
'404':
$ref: '#/components/responses/404-not-found'
delete:
tags:
- Admins
summary: Deleting admin.
description: |
Deletes an admin account.
responses:
'204':
$ref: '#/components/responses/204-no-content'
'401':
$ref: '#/components/responses/401-unauthorized'
'404':
$ref: '#/components/responses/404-not-found'
/admins/name/{name}:
parameters:
- $ref: '#/components/parameters/admin-name'
get:
tags:
- Admins
summary: Returning a single admin.
description: |
Returns information of a single admin account specified by its username.
responses:
'200':
$ref: '#/components/responses/client'
'401':
$ref: '#/components/responses/401-unauthorized'
'404':
$ref: '#/components/responses/404-not-found'
put:
tags:
- Admins
summary: Updating admin.
description: >
Updates an admin account.
Specify only the fields, you want to update.
If the following properties are part of the request but empty / null, they are auto-generated:
* password
If the following properties are auto-generated, they are part of the response:
* password
requestBody:
$ref: '#/components/requestBodies/admin-put'
responses:
'200':
$ref: '#/components/responses/200-ok-updated'
'400':
$ref: '#/components/responses/400-bad-request'
'401':
$ref: '#/components/responses/401-unauthorized'
'404':
$ref: '#/components/responses/404-not-found'
delete:
tags:
- Admins
summary: Deleting admin.
description: |
Deletes an admin account.
responses:
'204':
$ref: '#/components/responses/204-no-content'
'401':
$ref: '#/components/responses/401-unauthorized'
'404':
$ref: '#/components/responses/404-not-found'
/clients:
get:
tags:
- Clients
summary: Listing all clients.
description: |
Returns a list of all client accounts on the server.
You can use the following sort parameter values to sort the results.
* id (default)
* username
parameters:
- $ref: '#/components/parameters/clients-sort'
- $ref: '#/components/parameters/order'
responses:
'200':
$ref: '#/components/responses/client-array'
'401':
$ref: '#/components/responses/401-unauthorized'
post:
tags:
- Clients
summary: Creating a new client.
description: >
Creates a new client account.
To specify its account features, you should use a hosting plan, otherwise it is created with the default hosting plan.
Use the hosting plan endpoint to gather the information you need.
If the following properties are empty / not set, they are auto-generated:
* password
If the following properties are auto-generated, they are part of the response:
* password
requestBody:
$ref: '#/components/requestBodies/client-post'
responses:
'201':
$ref: '#/components/responses/201-created'
'400':
$ref: '#/components/responses/400-bad-request'
'401':
$ref: '#/components/responses/401-unauthorized'
/clients/{id}:
parameters:
- $ref: '#/components/parameters/client-id'
get:
tags:
- Clients
summary: Returning a single client.
description: |
Returns account details of a single client determined by its ID.
responses:
'200':
$ref: '#/components/responses/client'
'401':
$ref: '#/components/responses/401-unauthorized'
'404':
$ref: '#/components/responses/404-not-found'
put:
tags:
- Clients
summary: Updating client.
description: >
Updates a client account.
Specify only the fields, you want to update.
If the following properties are part of the request but empty / null, they are auto-generated:
* password
If the following properties are auto-generated, they are part of the response:
* password
requestBody:
$ref: '#/components/requestBodies/client-put'
responses:
'200':
$ref: '#/components/responses/200-ok-updated'
'400':
$ref: '#/components/responses/400-bad-request'
'401':
$ref: '#/components/responses/401-unauthorized'
'404':
$ref: '#/components/responses/404-not-found'
delete:
tags:
- Clients
summary: Deleting client.
description: |
Deletes a client account and all associated resources.
responses:
'204':
$ref: '#/components/responses/204-no-content'
'401':
$ref: '#/components/responses/401-unauthorized'
'404':
$ref: '#/components/responses/404-not-found'
/clients/{id}/resources:
parameters:
- $ref: '#/components/parameters/client-id'
- $ref: '#/components/parameters/client-resources-domains'
- $ref: '#/components/parameters/client-resources-certificates'
- $ref: '#/components/parameters/client-resources-emails'
- $ref: '#/components/parameters/client-resources-databases'
- $ref: '#/components/parameters/client-resources-ftp-users'
- $ref: '#/components/parameters/client-resources-scheduled-tasks'
- $ref: '#/components/parameters/client-resources-directory-protections'
get:
tags:
- Clients
summary: Listing all resources belonging to this client.
description: >
Returns an object consisting of all resources belonging to the specified client ID.
Properties are:
* domain items
* certificate items
* email items
* database items
* ftp user items
* scheduled task items
* directory protection items
If performance is a concern, you can use the query parameters, to query only for the information you need.
responses:
'200':
$ref: '#/components/responses/client-resources'
'401':
$ref: '#/components/responses/401-unauthorized'
'404':
$ref: '#/components/responses/404-not-found'
/clients/{id}/stats:
parameters:
- $ref: '#/components/parameters/client-id'
get:
tags:
- Clients
summary: Returning client statistics.
description: |
Returns the statistics of the client about its assigned resources and their usage.
responses:
'200':
$ref: '#/components/responses/client-stats'
'401':
$ref: '#/components/responses/401-unauthorized'
'404':
$ref: '#/components/responses/404-not-found'
/clients/{id}/traffic:
parameters:
- $ref: '#/components/parameters/client-id'
get:
tags:
- Clients
summary: Returning client traffic statisitc.
description: >
Returns the traffic statistic of the client of the current month.
You can use the following parameter to specify the month for which the statistics should be returned.
* month (Format YYYY-MM)
parameters:
- $ref: '#/components/parameters/client-traffic-month'
responses:
'200':
$ref: '#/components/responses/client-traffic'
'401':
$ref: '#/components/responses/401-unauthorized'
'404':
$ref: '#/components/responses/404-not-found'
/clients/name/{name}:
parameters:
- $ref: '#/components/parameters/client-name'
get:
tags:
- Clients
summary: Returning a single client.
description: >
Returns information of a single client account specified by its username.
responses:
'200':
$ref: '#/components/responses/client'
'401':
$ref: '#/components/responses/401-unauthorized'
'404':
$ref: '#/components/responses/404-not-found'
put:
tags:
- Clients
summary: Updating client.
description: >
Updates a client account.
Specify only the fields, you want to update.
If the following properties are part of the request but empty / null, they are auto-generated:
* password
If the following properties are auto-generated, they are part of the response:
* password
requestBody:
$ref: '#/components/requestBodies/client-put'
responses:
'200':
$ref: '#/components/responses/200-ok-updated'
'400':
$ref: '#/components/responses/400-bad-request'
'401':
$ref: '#/components/responses/401-unauthorized'
'404':
$ref: '#/components/responses/404-not-found'
delete:
tags:
- Clients
summary: Deleting client.
description: |
Deletes a client account and all associated resources.
responses:
'204':
$ref: '#/components/responses/204-no-content'
'401':
$ref: '#/components/responses/401-unauthorized'
'404':
$ref: '#/components/responses/404-not-found'
/clients/{name}/resources:
parameters:
- $ref: '#/components/parameters/client-name'
- $ref: '#/components/parameters/client-resources-domains'
- $ref: '#/components/parameters/client-resources-certificates'
- $ref: '#/components/parameters/client-resources-emails'
- $ref: '#/components/parameters/client-resources-databases'
- $ref: '#/components/parameters/client-resources-ftp-users'
- $ref: '#/components/parameters/client-resources-scheduled-tasks'
- $ref: '#/components/parameters/client-resources-directory-protections'
get:
tags:
- Clients
summary: Listing all resources belonging to this client.
description: >
Returns an object consisting of all resources belonging to the specified client ID.
Properties are:
* domain items
* certificate items
* email items
* database items
* ftp user items
* scheduled task items
* directory protection items
If performance is a concern, you can use the query parameters, to query only for the information you need.
responses:
'200':
$ref: '#/components/responses/client-resources'
'401':
$ref: '#/components/responses/401-unauthorized'
'404':
$ref: '#/components/responses/404-not-found'
/clients/{name}/stats:
parameters:
- $ref: '#/components/parameters/client-name'
get:
tags:
- Clients
summary: Returning client statistics.
description: |
Returns the statistics of the client about its assigned resources and their usage.
responses:
'200':
$ref: '#/components/responses/client-stats'
'401':
$ref: '#/components/responses/401-unauthorized'
'404':
$ref: '#/components/responses/404-not-found'
/clients/{name}/traffic:
parameters:
- $ref: '#/components/parameters/client-name'
get:
tags:
- Clients
summary: Returning client traffic statisitc.
description: >
Returns the traffic statistic of the client of the current month.
You can use the following parameter to specify the month for which the statistics should be returned.
* month (Format YYYY-MM)
parameters:
- $ref: '#/components/parameters/client-traffic-month'
responses:
'200':
$ref: '#/components/responses/client-traffic'
'401':
$ref: '#/components/responses/401-unauthorized'
'404':
$ref: '#/components/responses/404-not-found'
/hosting-plans:
get:
tags:
- Hosting plans
summary: Listing all hosting plans.
description: |
Returns a list of all hosting plans on the server.
You can use the following sort parameter values to sort the results.
* id (default)
* name
parameters:
- $ref: '#/components/parameters/hosting-plans-sort'
- $ref: '#/components/parameters/order'
responses:
'200':
$ref: '#/components/responses/hosting-plan-array'
'401':
$ref: '#/components/responses/401-unauthorized'
post:
tags:
- Hosting plans
summary: Creating a hosting plan.
description: >
Creates a new hosting plan.
You do not have to specify all available fields. Only the `name` field is required.<br>
Other fields are filled with default values, as it would be within the KeyHelp UI.
requestBody:
$ref: '#/components/requestBodies/hosting-plan-post'
responses:
'201':
$ref: '#/components/responses/201-created'
'400':
$ref: '#/components/responses/400-bad-request'
'401':
$ref: '#/components/responses/401-unauthorized'
/hosting-plans/{id}:
parameters:
- $ref: '#/components/parameters/hosting-plan-id'
get:
tags:
- Hosting plans
summary: Returning a single hosting plan.
description: |
Returns the features of a single hosting plan specified by its ID.
responses:
'200':
$ref: '#/components/responses/hosting-plan'
'401':
$ref: '#/components/responses/401-unauthorized'
'404':
$ref: '#/components/responses/404-not-found'
put:
tags:
- Hosting plans
summary: Updating hosting plan.
description: >
Updates a hosting plan item.
Please note that a hosting plan only serves as a template for client accounts.<br>
Client accounts are not automatically updated when a hosting plan is updated.
requestBody:
$ref: '#/components/requestBodies/hosting-plan-put'
responses:
'200':
$ref: '#/components/responses/200-ok-updated'
'400':
$ref: '#/components/responses/400-bad-request'
'401':
$ref: '#/components/responses/401-unauthorized'
'404':
$ref: '#/components/responses/404-not-found'
delete:
tags:
- Hosting plans
summary: Deleting a hosting plan.
description: |
Deletes a hosting plan.
responses:
'204':
$ref: '#/components/responses/204-no-content'
'401':
$ref: '#/components/responses/401-unauthorized'
'404':
$ref: '#/components/responses/404-not-found'
/hosting-plans/name/{name}:
parameters:
- $ref: '#/components/parameters/hosting-plan-name'
get:
tags:
- Hosting plans
summary: Returning a single hosting plan.
description: |
Returns the features of a single hosting plan specified by its name.
responses:
'200':
$ref: '#/components/responses/hosting-plan'
'401':
$ref: '#/components/responses/401-unauthorized'
'404':
$ref: '#/components/responses/404-not-found'
put:
tags:
- Hosting plans
summary: Updating hosting plan.
description: >
Updates a hosting plan item.
Please note that a hosting plan only serves as a template for client accounts.<br>
Client accounts are not automatically updated when a hosting plan is updated.
requestBody:
$ref: '#/components/requestBodies/hosting-plan-put'
responses:
'200':
$ref: '#/components/responses/200-ok-updated'
'400':
$ref: '#/components/responses/400-bad-request'
'401':
$ref: '#/components/responses/401-unauthorized'
'404':
$ref: '#/components/responses/404-not-found'
delete:
tags:
- Hosting plans
summary: Deleting a hosting plan.
description: |
Deletes a hosting plan.
responses:
'204':
$ref: '#/components/responses/204-no-content'
'401':
$ref: '#/components/responses/401-unauthorized'
'404':
$ref: '#/components/responses/404-not-found'
/domains:
get:
tags:
- Domains
summary: Listing all domains.
description: |
Returns a list of all domains on this server.
You can use the following filter parameter values to filter the results.
* main_domains
* subdomains
* system_domains
You can use the following sort parameter values to sort the results.
* id (default)
* domain
* domain_utf8
parameters:
- $ref: '#/components/parameters/domains-sort'
- $ref: '#/components/parameters/order'
- $ref: '#/components/parameters/domains-main-domains'
- $ref: '#/components/parameters/domains-subdomains'
- $ref: '#/components/parameters/domains-system-domains'
responses:
'200':
$ref: '#/components/responses/domain-array'
'401':
$ref: '#/components/responses/401-unauthorized'
post:
tags:
- Domains
summary: Creating a domain.
description: |
Creates a new domain.
requestBody:
$ref: '#/components/requestBodies/domain-post'
responses:
'201':
$ref: '#/components/responses/201-created'
'400':
$ref: '#/components/responses/400-bad-request'
'401':
$ref: '#/components/responses/401-unauthorized'
/domains/{id}:
parameters:
- $ref: '#/components/parameters/domain-id'
get:
tags:
- Domains
summary: Returning a single domain.
description: |
Returns information of a single domain specified by its ID.
responses:
'200':
$ref: '#/components/responses/domain'
'401':
$ref: '#/components/responses/401-unauthorized'
'404':
$ref: '#/components/responses/404-not-found'
put:
tags:
- Domains
summary: Updating a domain.
description: |
Updates a domain item.
requestBody:
$ref: '#/components/requestBodies/domain-put'
responses:
'200':
$ref: '#/components/responses/200-ok-updated'
'400':
$ref: '#/components/responses/400-bad-request'
'401':
$ref: '#/components/responses/401-unauthorized'
'404':
$ref: '#/components/responses/404-not-found'
delete:
tags:
- Domains
summary: Deleting a domain.
description: |
Deletes a domain item.
responses:
'204':
$ref: '#/components/responses/204-no-content'
'401':
$ref: '#/components/responses/401-unauthorized'
'404':
$ref: '#/components/responses/404-not-found'
/domains/name/{name}:
parameters:
- $ref: '#/components/parameters/domain-name'
get:
tags:
- Domains
summary: Returning a single domain.
description: |
Returns information of a single domain specified by its domain name.
responses:
'200':
$ref: '#/components/responses/domain'
'401':
$ref: '#/components/responses/401-unauthorized'
'404':
$ref: '#/components/responses/404-not-found'
put:
tags:
- Domains
summary: Updating a domain.
description: |
Updates a domain item.
requestBody:
$ref: '#/components/requestBodies/domain-put'
responses:
'200':
$ref: '#/components/responses/200-ok-updated'
'400':
$ref: '#/components/responses/400-bad-request'
'401':
$ref: '#/components/responses/401-unauthorized'
'404':
$ref: '#/components/responses/404-not-found'
delete:
tags:
- Domains
summary: Deleting a domain.
description: |
Deletes a domain item.
responses:
'204':
$ref: '#/components/responses/204-no-content'
'401':
$ref: '#/components/responses/401-unauthorized'
'404':
$ref: '#/components/responses/404-not-found'
/dns/{id}:
parameters:
- $ref: '#/components/parameters/domain-id'
get:
tags:
- DNS
summary: Listing the DNS records of a domain.
description: >
Lists the currently active DNS records for a domain ID.
Only IDs of main domains are allowed, IDs of subdomains will result in a 404 error.
The placeholder `<DKIM_RECORD_VALUE>` in the `value` field of a record will be replace with the actual DKIM record.
responses:
'200':
$ref: '#/components/responses/dns'
'401':
$ref: '#/components/responses/401-unauthorized'
'404':
$ref: '#/components/responses/404-not-found'
put:
tags:
- DNS
summary: Updating the DNS records of a domain
description: >
Updates the DNS records of domain ID.
Only IDs of main domains are allowed, IDs of subdomains will result in a 404 error.
Attention, when inserting custom DNS records, you have to specify all records not just the one you want to update.
If the property `is_dns_disabled`, either set to `true` or `false`, is part of the request, all specified records of the request will be ignored.
* If `is_dns_disabled` is set to `true` -> DNS will be disabled
* If `is_dns_disabled` is set to `false` -> DNS will be enabled with the default DNS settings
If you want to enable DNS and insert custom DNS records with only one request, simply send your DNS records without the `is_dns_disabled` property being part of the request.
The placeholder `<DKIM_RECORD_VALUE>` in the `value` field of a record will be replace with the actual DKIM record.
requestBody:
$ref: '#/components/requestBodies/dns-put'
responses:
'200':
$ref: '#/components/responses/200-ok-updated'
'400':
$ref: '#/components/responses/400-bad-request'
'401':
$ref: '#/components/responses/401-unauthorized'
'404':
$ref: '#/components/responses/404-not-found'
delete:
tags:
- DNS
summary: Deleting the custom DNS settings of the domain.
description: >
Calling this endpoint removes all custom settings from the domains' DNS settings:
* A previously disabled DNS will be activated.
* The SOA and all other DNS records are reset to their default values.
responses:
'204':
$ref: '#/components/responses/204-no-content'
'401':
$ref: '#/components/responses/401-unauthorized'
'404':
$ref: '#/components/responses/404-not-found'
/dns/name/{name}:
parameters:
- $ref: '#/components/parameters/domain-name'
get:
tags:
- DNS
summary: Listing the DNS records of a domain.
description: >
Lists the currently active DNS records for a domain ID.
Only IDs of main domains are allowed, IDs of subdomains will result in a 404 error.
The placeholder `<DKIM_RECORD_VALUE>` in the `value` field of a record will be replace with the actual DKIM record.
responses:
'200':
$ref: '#/components/responses/dns'
'401':
$ref: '#/components/responses/401-unauthorized'
'404':
$ref: '#/components/responses/404-not-found'
put:
tags:
- DNS
summary: Updating the DNS records of a domain
description: >
Updates the DNS records of domain ID.
Only IDs of main domains are allowed, IDs of subdomains will result in a 404 error.
Attention, when inserting custom DNS records, you have to specify all records not just the one you want to update.
If the property `is_dns_disabled`, either set to `true` or `false`, is part of the request, all specified records of the request will be ignored.
* If `is_dns_disabled` is set to `true` -> DNS will be disabled
* If `is_dns_disabled` is set to `false` -> DNS will be enabled with the default DNS settings
If you want to enable DNS and insert custom DNS records with only one request, simply send your DNS records without the `is_dns_disabled` property being part of the request.
The placeholder `<DKIM_RECORD_VALUE>` in the `value` field of a record will be replace with the actual DKIM record.
requestBody:
$ref: '#/components/requestBodies/dns-put'
responses:
'200':
$ref: '#/components/responses/200-ok-updated'
'400':
$ref: '#/components/responses/400-bad-request'
'401':
$ref: '#/components/responses/401-unauthorized'
'404':
$ref: '#/components/responses/404-not-found'
delete:
tags:
- DNS
summary: Deleting the custom DNS settings of the domain.
description: >
Calling this endpoint removes all custom settings from the domains' DNS settings:
* A previously disabled DNS will be activated.
* The SOA and all other DNS records are reset to their default values.
responses:
'204':
$ref: '#/components/responses/204-no-content'
'401':
$ref: '#/components/responses/401-unauthorized'
'404':
$ref: '#/components/responses/404-not-found'
/certificates:
get:
tags:
- Certificates
summary: Listing all certificates.
description: |
Returns a list of all certificates on the server.
You can use the following sort parameter values to sort the results.
* id (default)
* name
parameters:
- $ref: '#/components/parameters/certificates-sort'
- $ref: '#/components/parameters/order'
responses:
'200':
$ref: '#/components/responses/certificate-array'
'401':
$ref: '#/components/responses/401-unauthorized'
post:
tags:
- Certificates
summary: Creating a certificate.
description: |
Creates a new certificate.
requestBody:
$ref: '#/components/requestBodies/certificate-post'
responses:
'201':
$ref: '#/components/responses/201-created'
'400':
$ref: '#/components/responses/400-bad-request'
'401':
$ref: '#/components/responses/401-unauthorized'
/certificates/{id}:
parameters:
- $ref: '#/components/parameters/certificate-id'
get:
tags:
- Certificates
summary: Returning a single certificate.
description: |
Returns information of a single certificate specified by its ID.
responses:
'200':
$ref: '#/components/responses/certificate'
'401':
$ref: '#/components/responses/401-unauthorized'
'404':
$ref: '#/components/responses/404-not-found'
put:
tags:
- Certificates
summary: Updating a certificate.
description: |
Updates a certificate.
Specify only the fields, you want to update.
requestBody:
$ref: '#/components/requestBodies/certificate-put'
responses:
'200':
$ref: '#/components/responses/200-ok-updated'
'400':
$ref: '#/components/responses/400-bad-request'
'401':
$ref: '#/components/responses/401-unauthorized'
'404':
$ref: '#/components/responses/404-not-found'
delete:
tags:
- Certificates
summary: Deleting a certificate.
description: |
Deletes a certificate.
responses:
'204':
$ref: '#/components/responses/204-no-content'
'401':
$ref: '#/components/responses/401-unauthorized'
'404':
$ref: '#/components/responses/404-not-found'
/certificates/name/{name}:
parameters:
- $ref: '#/components/parameters/certificate-name'
get:
tags:
- Certificates
summary: Returning a single certificate.
description: |
Returns information of a single certificate specified by its name.
responses:
'200':
$ref: '#/components/responses/certificate'
'401':
$ref: '#/components/responses/401-unauthorized'
'404':
$ref: '#/components/responses/404-not-found'
put:
tags:
- Certificates
summary: Updating a certificate.
description: |
Updates a certificate.
Specify only the fields, you want to update.
requestBody:
$ref: '#/components/requestBodies/certificate-put'
responses:
'200':
$ref: '#/components/responses/200-ok-updated'
'400':
$ref: '#/components/responses/400-bad-request'
'401':
$ref: '#/components/responses/401-unauthorized'
'404':
$ref: '#/components/responses/404-not-found'
delete:
tags:
- Certificates
summary: Deleting a certificate.
description: |
Deletes a certificate.
responses:
'204':
$ref: '#/components/responses/204-no-content'
'401':
$ref: '#/components/responses/401-unauthorized'
'404':
$ref: '#/components/responses/404-not-found'
/emails:
get:
tags:
- Emails
summary: Listing all email accounts.
description: |
Returns a list of all email accounts on the server.
You can use the following sort parameter values to sort the results.
* id (default)
* email
* email_utf8
parameters:
- $ref: '#/components/parameters/emails-sort'
- $ref: '#/components/parameters/order'
responses:
'200':
$ref: '#/components/responses/email-array'
'401':
$ref: '#/components/responses/401-unauthorized'
post:
tags:
- Emails
summary: Creating an email account.
description: >
Creates a new email account.
If the following properties accepts punycode and UTF-8 domain names:
* email
* aliases
* forwardings
If the following properties are empty / not set, they are auto-generated:
* password
If the following properties are auto-generated, they are part of the response:
* password
requestBody:
$ref: '#/components/requestBodies/email-post'
responses:
'201':
$ref: '#/components/responses/201-created'
'400':
$ref: '#/components/responses/400-bad-request'
'401':
$ref: '#/components/responses/401-unauthorized'
/emails/{id}:
parameters:
- $ref: '#/components/parameters/email-id'
get:
tags:
- Emails
summary: Returning a single email account.
description: |
Returns information of a single email account specified by its ID.
responses:
'200':
$ref: '#/components/responses/email'
'401':
$ref: '#/components/responses/401-unauthorized'
'404':
$ref: '#/components/responses/404-not-found'
put:
tags:
- Emails
summary: Updating an email account.
description: >
Updates an email account.
Specify only the fields, you want to update.
If the following properties accepts punycode and UTF-8 domain names:
* aliases
* forwardings
If the following properties are part of the request but empty / null, they are auto-generated:
* password
If the following properties are auto-generated, they are part of the response:
* password
requestBody:
$ref: '#/components/requestBodies/email-put'
responses:
'200':
$ref: '#/components/responses/200-ok-updated'
'400':
$ref: '#/components/responses/400-bad-request'
'401':
$ref: '#/components/responses/401-unauthorized'
'404':
$ref: '#/components/responses/404-not-found'
delete:
tags:
- Emails
summary: Deleting an email account.
description: |
Deletes an email account.
responses:
'204':
$ref: '#/components/responses/204-no-content'
'401':
$ref: '#/components/responses/401-unauthorized'
'404':
$ref: '#/components/responses/404-not-found'
/emails/name/{name}:
parameters:
- $ref: '#/components/parameters/email-name'
get:
tags:
- Emails
summary: Returning a single email account.
description: >
Returns information of a single email account specified by its email address.
responses:
'200':
$ref: '#/components/responses/email'
'401':
$ref: '#/components/responses/401-unauthorized'
'404':
$ref: '#/components/responses/404-not-found'
put:
tags:
- Emails
summary: Updating an email account.
description: >
Updates an email account.
Specify only the fields, you want to update.
If the following properties accepts punycode and UTF-8 domain names:
* aliases
* forwardings
If the following properties are part of the request but empty / null, they are auto-generated:
* password
If the following properties are auto-generated, they are part of the response:
* password
requestBody:
$ref: '#/components/requestBodies/email-put'
responses:
'200':
$ref: '#/components/responses/200-ok-updated'
'400':
$ref: '#/components/responses/400-bad-request'
'401':
$ref: '#/components/responses/401-unauthorized'
'404':
$ref: '#/components/responses/404-not-found'
delete:
tags:
- Emails
summary: Deleting an email account.
description: |
Deletes an email account.
responses:
'204':
$ref: '#/components/responses/204-no-content'
'401':
$ref: '#/components/responses/401-unauthorized'
'404':
$ref: '#/components/responses/404-not-found'
/databases:
get:
tags:
- Databases
summary: Listing all databases.
description: |
Returns a list of all databases on the server.
You can use the following sort parameter values to sort the results.
* id (default)
* database_name
* database_username
parameters:
- $ref: '#/components/parameters/databases-sort'
- $ref: '#/components/parameters/order'
responses:
'200':
$ref: '#/components/responses/database-array'
'401':
$ref: '#/components/responses/401-unauthorized'
post:
tags:
- Databases
summary: Creating a database and database user.
description: >
Creates a new database.
If the following properties are empty / not set, they are auto-generated:
* database_name and database_username
* password
If the following properties are auto-generated, they are part of the response:
* database_name and database_username
* password
requestBody:
$ref: '#/components/requestBodies/database-post'
responses:
'201':
$ref: '#/components/responses/201-created'
'400':
$ref: '#/components/responses/400-bad-request'
'401':
$ref: '#/components/responses/401-unauthorized'
/databases/{id}:
parameters:
- $ref: '#/components/parameters/database-id'
get:
tags:
- Databases
summary: Returning a single database and its database user.
description: >
Returns information of a database and its database user specified by its ID.
responses:
'200':
$ref: '#/components/responses/database'
'401':
$ref: '#/components/responses/401-unauthorized'
'404':
$ref: '#/components/responses/404-not-found'
put:
tags:
- Databases
summary: Updating a database and its database user.
description: >
Updates a database and its database user.
Specify only the fields, you want to update.
If the following properties are part of the request but empty / null, they are auto-generated:
* password
If the following properties are auto-generated, they are part of the response:
* password
requestBody:
$ref: '#/components/requestBodies/database-put'
responses:
'200':
$ref: '#/components/responses/200-ok-updated'
'400':
$ref: '#/components/responses/400-bad-request'
'401':
$ref: '#/components/responses/401-unauthorized'
'404':
$ref: '#/components/responses/404-not-found'
delete:
tags:
- Databases
summary: Deleting a database and its database user.
description: |
Deletes a database and its database user.
responses:
'204':
$ref: '#/components/responses/204-no-content'
'401':
$ref: '#/components/responses/401-unauthorized'
'404':
$ref: '#/components/responses/404-not-found'
/databases/name/{name}:
parameters:
- $ref: '#/components/parameters/database-name'
get:
tags:
- Databases
summary: Returning a single database and its database user.
description: >
Returns information of a database and its database user specified by its database name.
responses:
'200':
$ref: '#/components/responses/database'
'401':
$ref: '#/components/responses/401-unauthorized'
'404':
$ref: '#/components/responses/404-not-found'
put:
tags:
- Databases
summary: Updating a database and its database user.
description: >
Updates a database and its database user.
Specify only the fields, you want to update.
If the following properties are part of the request but empty / null, they are auto-generated:
* password
If the following properties are auto-generated, they are part of the response:
* password
requestBody:
$ref: '#/components/requestBodies/database-put'
responses:
'200':
$ref: '#/components/responses/200-ok-updated'
'400':
$ref: '#/components/responses/400-bad-request'
'401':
$ref: '#/components/responses/401-unauthorized'
'404':
$ref: '#/components/responses/404-not-found'
delete:
tags:
- Databases
summary: Deleting a database and its database user.
description: |
Deletes a database and its database user.
responses:
'204':
$ref: '#/components/responses/204-no-content'
'401':
$ref: '#/components/responses/401-unauthorized'
'404':
$ref: '#/components/responses/404-not-found'
/ftp-users:
get:
tags:
- FTP users
summary: Listing all FTP users.
description: |
Returns a list of all FTP users on the server.
You can use the following sort parameter values to sort the results.
* id (default)
* username
parameters:
- $ref: '#/components/parameters/ftp-users-sort'
- $ref: '#/components/parameters/order'
responses:
'200':
$ref: '#/components/responses/ftp-user-array'
'401':
$ref: '#/components/responses/401-unauthorized'
post:
tags:
- FTP users
summary: Creating a FTP user.
description: >
Creates a new FTP user.
**Please note**, to create a new FTP user, it is required that the corresponding (system) user account is fully set up.
Otherwise you will receive the **400 Bad Request** error:<br>
**Invalid property data for: 'uid', 'gid'**
If the following properties are empty / not set, they are auto-generated:
* username
* password
* home_directory (defaults to /www/)
If the following properties are auto-generated, they are part of the response:
* username
* password
requestBody:
$ref: '#/components/requestBodies/ftp-user-post'
responses:
'201':
$ref: '#/components/responses/201-created'
'400':
$ref: '#/components/responses/400-bad-request'
'401':
$ref: '#/components/responses/401-unauthorized'
/ftp-users/{id}:
parameters:
- $ref: '#/components/parameters/ftp-user-id'
get:
tags:
- FTP users
summary: Returning a single FTP user.
description: |
Returns information of a single FTP user specified by its ID.
responses:
'200':
$ref: '#/components/responses/ftp-user'
'401':
$ref: '#/components/responses/401-unauthorized'
'404':
$ref: '#/components/responses/404-not-found'
put:
tags:
- FTP users
summary: Updating a FTP account.
description: >
Updates a FTP user.
Specify only the fields, you want to update.
If the following properties are part of the request but empty / null, they are auto-generated:
* password
If the following properties are auto-generated, they are part of the response:
* password
requestBody:
$ref: '#/components/requestBodies/ftp-user-put'
responses:
'200':
$ref: '#/components/responses/200-ok-updated'
'400':
$ref: '#/components/responses/400-bad-request'
'401':
$ref: '#/components/responses/401-unauthorized'
'404':
$ref: '#/components/responses/404-not-found'
delete:
tags:
- FTP users
summary: Deleting a FTP user.
description: |
Deletes a FTP user.
responses:
'204':
$ref: '#/components/responses/204-no-content'
'401':
$ref: '#/components/responses/401-unauthorized'
'404':
$ref: '#/components/responses/404-not-found'
/ftp-users/name/{name}:
parameters:
- $ref: '#/components/parameters/ftp-user-name'
get:
tags:
- FTP users
summary: Returning a single FTP user.
description: |
Returns information of a FTP user specified by its username.
responses:
'200':
$ref: '#/components/responses/ftp-user'
'401':
$ref: '#/components/responses/401-unauthorized'
'404':
$ref: '#/components/responses/404-not-found'
put:
tags:
- FTP users
summary: Updating a FTP account.
description: >
Updates a FTP user.
Specify only the fields, you want to update.
If the following properties are part of the request but empty / null, they are auto-generated:
* password
If the following properties are auto-generated, they are part of the response:
* password
requestBody:
$ref: '#/components/requestBodies/ftp-user-put'
responses:
'200':
$ref: '#/components/responses/200-ok-updated'
'400':
$ref: '#/components/responses/400-bad-request'
'401':
$ref: '#/components/responses/401-unauthorized'
'404':
$ref: '#/components/responses/404-not-found'
delete:
tags:
- FTP users
summary: Deleting a FTP user.
description: |
Deletes a FTP user.
responses:
'204':
$ref: '#/components/responses/204-no-content'
'401':
$ref: '#/components/responses/401-unauthorized'
'404':
$ref: '#/components/responses/404-not-found'
/scheduled-tasks:
get:
tags:
- Scheduled tasks
summary: Listing all scheduled tasks.
description: |
Returns a list of all scheduled tasks on the server.
You can use the following sort parameter values to sort the results.
* id (default)
* type
parameters:
- $ref: '#/components/parameters/scheduled-tasks-sort'
- $ref: '#/components/parameters/order'
responses:
'200':
$ref: '#/components/responses/scheduled-task-array'
'401':
$ref: '#/components/responses/401-unauthorized'
post:
tags:
- Scheduled tasks
summary: Creating a scheduled tasks.
description: |
Creates a new scheduled tasks.
requestBody:
$ref: '#/components/requestBodies/scheduled-task-post'
responses:
'201':
$ref: '#/components/responses/201-created'
'400':
$ref: '#/components/responses/400-bad-request'
'401':
$ref: '#/components/responses/401-unauthorized'
/scheduled-tasks/{id}:
parameters:
- $ref: '#/components/parameters/scheduled-task-id'
get:
tags:
- Scheduled tasks
summary: Returning a single scheduled task.
description: |
Returns information of a scheduled task specified by its ID.
responses:
'200':
$ref: '#/components/responses/scheduled-task'
'401':
$ref: '#/components/responses/401-unauthorized'
'404':
$ref: '#/components/responses/404-not-found'
put:
tags:
- Scheduled tasks
summary: Updating a scheduled task.
description: >
Updates a scheduled tasks.
Specify only the fields, you want to update. Read the exception below!
ATTENTION! When updating the schedule settings, all missing schedule fields in the request will default to `*`.
As an example, imagine you have a scheduled task with the following settings:<br>
`minutes = 10`, `hour = 4`, `day_of_week = *`, `month = *`, `day_of_month = 1`
If you now only want to update the `minute` value, you have to include at least `hour` and `day_of_month` values also, to keep their settings.
If you don't do it, and only set the `minutes`, all other values will default to `*`. You would end up with the following:<br>
`minutes` = 10, `hour = *`, `day_of_week = *`, `month = *`, `day_of_month = *`
requestBody:
$ref: '#/components/requestBodies/scheduled-task-put'
responses:
'200':
$ref: '#/components/responses/200-ok-updated'
'400':
$ref: '#/components/responses/400-bad-request'
'401':
$ref: '#/components/responses/401-unauthorized'
'404':
$ref: '#/components/responses/404-not-found'
delete:
tags:
- Scheduled tasks
summary: Deleting a scheduled tasks.
description: |
Deletes a scheduled tasks.
responses:
'204':
$ref: '#/components/responses/204-no-content'
'401':
$ref: '#/components/responses/401-unauthorized'
'404':
$ref: '#/components/responses/404-not-found'
/directory-protections:
get:
tags:
- Directory protections
summary: Listing all directory protections.
description: |
Returns a list of all directory protections on the server.
You can use the following sort parameter values to sort the results.
* id (default)
* auth_name
* username
parameters:
- $ref: '#/components/parameters/directory-protections-sort'
- $ref: '#/components/parameters/order'
responses:
'200':
$ref: '#/components/responses/directory-protection-array'
'401':
$ref: '#/components/responses/401-unauthorized'
post:
tags:
- Directory protections
summary: Creating a directory protection.
description: >
Creates a new directory protection.
If the following properties are empty / not set, they are auto-generated:
* password
* path (defaults to /, which corresponds to the user's /www/ directory)
If the following properties are auto-generated, they are part of the response:
* password
requestBody:
$ref: '#/components/requestBodies/directory-protection-post'
responses:
'201':
$ref: '#/components/responses/201-created'
'400':
$ref: '#/components/responses/400-bad-request'
'401':
$ref: '#/components/responses/401-unauthorized'
/directory-protections/{id}:
parameters:
- $ref: '#/components/parameters/directory-protection-id'
get:
tags:
- Directory protections
summary: Returning a single directory protection.
description: >
Returns information of a single directory protection specified by its ID.
responses:
'200':
$ref: '#/components/responses/directory-protection'
'401':
$ref: '#/components/responses/401-unauthorized'
'404':
$ref: '#/components/responses/404-not-found'
put:
tags:
- Directory protections
summary: Updating a directory protection.
description: >
Updates a directory protection.
Specify only the fields, you want to update.
If the following properties are part of the request but empty / null, they are auto-generated:
* password
requestBody:
$ref: '#/components/requestBodies/directory-protection-put'
responses:
'200':
$ref: '#/components/responses/200-ok-updated'
'400':
$ref: '#/components/responses/400-bad-request'
'401':
$ref: '#/components/responses/401-unauthorized'
'404':
$ref: '#/components/responses/404-not-found'
delete:
tags:
- Directory protections
summary: Deleting a directory protection.
description: |
Deletes a directory protection.
responses:
'204':
$ref: '#/components/responses/204-no-content'
'401':
$ref: '#/components/responses/401-unauthorized'
'404':
$ref: '#/components/responses/404-not-found'
components:
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: X-API-Key
parameters:
order:
name: order
in: query
description: The direction you want to sort.
required: false
schema:
type: string
enum:
- asc
- desc
default: asc
server-meta:
name: meta
in: query
description: Show the **meta** component.
required: false
schema:
type: boolean
default: true
server-operating-system:
name: operating_system
in: query
description: Show the **operating_system** component.
required: false
schema:
type: boolean
default: true
server-utilization:
name: utilization
in: query
description: Show the **utilization** component.
required: false
schema:
type: boolean
default: true
server-resources:
name: resources
in: query
description: Show the **resources** component.
required: false
schema:
type: boolean
default: true
server-components:
name: components
in: query
description: Show the **components** component.
required: false
schema:
type: boolean
default: true
server-additional-php-interpreters:
name: additional_php_interpreters
in: query
description: Show the **additional_php_interpreters** component.
required: false
schema:
type: boolean
default: true
server-ports:
name: ports
in: query
description: Show the **service/ports** component.
required: false
schema:
type: boolean
default: true
admins-sort:
name: sort
in: query
description: The property you want to sort by.
required: false
schema:
type: string
enum:
- id
- username
default: id
admin-id:
name: id
in: path
description: User ID.
required: true
schema:
type: integer
minimum: 1
admin-name:
name: name
in: path
description: Username.
required: true
schema:
type: string
clients-sort:
name: sort
in: query
description: The property you want to sort by.
required: false
schema:
type: string
enum:
- id
- username
default: id
client-id:
name: id
in: path
description: User ID.
required: true
schema:
type: integer
minimum: 1
client-name:
name: name
in: path
description: Username.
required: true
schema:
type: string
client-traffic-month:
name: month
in: query
description: Month (Format YYYY-MM).
required: false
schema:
type: string
client-resources-domains:
name: domains
in: query
description: Show the **domains** component.
required: false
schema:
type: boolean
default: true
client-resources-certificates:
name: certificates
in: query
description: Show the **certificates** component.
required: false
schema:
type: boolean
default: true
client-resources-emails:
name: emails
in: query
description: Show the **emails** component.
required: false
schema:
type: boolean
default: true
client-resources-databases:
name: databases
in: query
description: Show the **databases** component.
required: false
schema:
type: boolean
default: true
client-resources-ftp-users:
name: ftp_users
in: query
description: Show the **ftp_users** component.
required: false
schema:
type: boolean
default: true
client-resources-scheduled-tasks:
name: scheduled_tasks
in: query
description: Show the **scheduled_tasks** component.
required: false
schema:
type: boolean
default: true
client-resources-directory-protections:
name: directory_protections
in: query
description: Show the **directory_protections** component.
required: false
schema:
type: boolean
default: true
hosting-plans-sort:
name: sort
in: query
description: The property you want to sort by.
required: false
schema:
type: string
enum:
- id
- name
default: id
hosting-plan-id:
name: id
in: path
description: Numeric ID of the hosting plan.
required: true
schema:
type: integer
minimum: 1
hosting-plan-name:
name: name
in: path
description: Hosting plan name.
required: true
schema:
type: string
domains-sort:
name: sort
in: query
description: The property you want to sort by.
required: false
schema:
type: string
enum:
- id
- domain
- domain_utf8
default: id
domains-main-domains:
name: main_domains
in: query
description: Show main domains.
required: false
schema:
type: boolean
default: true
domains-subdomains:
name: subdomains
in: query
description: Show subdomains.
required: false
schema:
type: boolean
default: true
domains-system-domains:
name: system-domains
in: query
description: >
Filters the result for system domains. It will not return any data, when main_domains and subdomains are set to false.
required: false
schema:
type: boolean
default: true
domain-id:
name: id
in: path
description: Domain ID.
required: true
schema:
type: integer
minimum: 1
domain-name:
name: name
in: path
description: Domain in either UTF-8 or punycode variant.
required: true
schema:
type: string
certificates-sort:
name: sort
in: query
description: The property you want to sort by.
required: false
schema:
type: string
enum:
- id
- name
default: id
certificate-id:
name: id
in: path
description: Certificate ID.
required: true
schema:
type: integer
minimum: 1
certificate-name:
name: name
in: path
description: Certificate name.
required: true
schema:
type: string
emails-sort:
name: sort
in: query
description: The property you want to sort by.
required: false
schema:
type: string
enum:
- id
- email
- email_utf8
default: id
email-id:
name: id
in: path
description: Email account ID.
required: true
schema:
type: integer
minimum: 1
email-name:
name: name
in: path
description: Email account name (= email address).
required: true
schema:
type: string
databases-sort:
name: sort
in: query
description: The property you want to sort by.
required: false
schema:
type: string
enum:
- id
- database_name
- database_username
default: id
database-id:
name: id
in: path
description: Database ID.
required: true
schema:
type: integer
minimum: 1
database-name:
name: name
in: path
description: Database name.
required: true
schema:
type: string
ftp-users-sort:
name: sort
in: query
description: The property you want to sort by.
required: false
schema:
type: string
enum:
- id
- username
default: id
ftp-user-id:
name: id
in: path
description: Numeric ID of the FTP user to get.
required: true
schema:
type: integer
minimum: 1
ftp-user-name:
name: name
in: path
description: FTP user username.
required: true
schema:
type: string
scheduled-tasks-sort:
name: sort
in: query
description: The property you want to sort by.
required: false
schema:
type: string
enum:
- id
- type
default: id
scheduled-task-id:
name: id
in: path
description: Numeric ID of the scheduled task to get.
required: true
schema:
type: integer
minimum: 1
directory-protections-sort:
name: sort
in: query
description: The property you want to sort by.
required: false
schema:
type: string
enum:
- id
- auth_name
- username
default: id
directory-protection-id:
name: id
in: path
description: Numeric ID of the directory protection to get.
required: true
schema:
type: integer
minimum: 1
requestBodies:
admin-post:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/admin'
admin-put:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/admin'
example:
language: en
email: new@example.com
password: qwertz
client-post:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/client'
client-put:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/client'
example:
language: en
email: new@example.com
password: qwertz
id_hosting_plan: 5
contact_data:
company: NewCompanyName Inc.
hosting-plan-post:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/hosting-plan'
hosting-plan-put:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/hosting-plan'
example:
name: Hosting Premium
resources:
disk_space: 100G
domains: 100
databases: 100
permissions:
ssh: true
ssh_jail: true
domain-post:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/domain'
domain-put:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/domain'
example:
target: https://www.keyhelp.de
security:
lets_encrypt: false
is_prefer_https: false
dns-put:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/dns'
example:
records:
soa:
ttl: 86400
primary_ns: ns.example.com.
rname: root.example.com.
refresh: 14400
retry: 1800
expire: 60480
minimum: 3600
other:
- host: '@'
ttl: 86400
type: A
value: 192.168.178.1
- host: '*'
ttl: 86400
type: A
value: 192.168.178.1
- host: '@'
ttl: 86400
type: NS
value: ns.example.com.
- host: default._domainkey
ttl: 86400
type: TXT
value: <DKIM_RECORD_VALUE>
certificate-post:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/certificate'
certificate-put:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/certificate'
example:
id_user: null
name: Certificate for example.com until 2022
certificate: '-----BEGIN CERTIFICATE----- ... -----END CERTIFICATE-----'
ca_certificate: '-----BEGIN CERTIFICATE----- ... -----END CERTIFICATE-----'
email-post:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/email'
email-put:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/email'
example:
aliases:
- john.doe@example.com
- jane.doe@example.com
database-post:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/database'
database-put:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/database'
example:
password: qwertz
description: Description for this database.
remote_hosts: null
ftp-user-post:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ftp-user'
ftp-user-put:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ftp-user'
example:
description: Description for this FTP user.
home_directory: /www/website/images/new
password: qwertz
scheduled-task-post:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/scheduled-task'
scheduled-task-put:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/scheduled-task'
example:
command: bash /path/to/script.sh --debug
description: Run my script in debug mode
notify: always
email: info@keyhelp.de
schedule:
minute: '*/2'
hour: '*'
directory-protection-post:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/directory-protection'
directory-protection-put:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/directory-protection'
example:
username: john_doe
password: qwertz
responses:
server:
description: OK.
content:
application/json:
schema:
$ref: '#/components/schemas/server'
ping:
description: OK.
content:
application/json:
schema:
$ref: '#/components/schemas/ping'
login-url:
description: OK.
content:
application/json:
schema:
$ref: '#/components/schemas/login-url'
admin:
description: OK.
content:
application/json:
schema:
$ref: '#/components/schemas/admin'
admin-array:
description: OK.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/admin'
client:
description: OK.
content:
application/json:
schema:
$ref: '#/components/schemas/client'
client-array:
description: OK.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/client'
client-resources:
description: OK.
content:
application/json:
schema:
type: object
properties:
domains:
type: array
items:
$ref: '#/components/schemas/domain'
certificates:
type: array
items:
$ref: '#/components/schemas/certificate'
emails:
type: array
items:
$ref: '#/components/schemas/email'
databases:
type: array
items:
$ref: '#/components/schemas/database'
ftp_users:
type: array
items:
$ref: '#/components/schemas/ftp-user'
scheduled_tasks:
type: array
items:
$ref: '#/components/schemas/scheduled-task'
directory_protections:
type: array
items:
$ref: '#/components/schemas/directory-protection'
client-stats:
description: OK.
content:
application/json:
schema:
$ref: '#/components/schemas/client-stats'
client-traffic:
description: OK.
content:
application/json:
schema:
$ref: '#/components/schemas/client-traffic'
hosting-plan:
description: OK.
content:
application/json:
schema:
$ref: '#/components/schemas/hosting-plan'
hosting-plan-array:
description: OK.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/hosting-plan'
domain:
description: OK.
content:
application/json:
schema:
$ref: '#/components/schemas/domain'
domain-array:
description: OK.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/domain'
dns:
description: OK.
content:
application/json:
schema:
$ref: '#/components/schemas/dns'
certificate:
description: OK.
content:
application/json:
schema:
$ref: '#/components/schemas/certificate'
certificate-array:
description: OK.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/certificate'
email:
description: OK.
content:
application/json:
schema:
$ref: '#/components/schemas/email'
email-array:
description: OK.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/email'
database:
description: OK.
content:
application/json:
schema:
$ref: '#/components/schemas/database'
database-array:
description: OK.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/database'
ftp-user:
description: OK.
content:
application/json:
schema:
$ref: '#/components/schemas/ftp-user'
ftp-user-array:
description: OK.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/ftp-user'
scheduled-task:
description: OK.
content:
application/json:
schema:
$ref: '#/components/schemas/scheduled-task'
scheduled-task-array:
description: OK.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/scheduled-task'
directory-protection:
description: OK.
content:
application/json:
schema:
$ref: '#/components/schemas/directory-protection'
directory-protection-array:
description: OK.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/directory-protection'
200-ok:
description: OK.
200-ok-updated:
description: OK.
content:
application/json:
schema:
$ref: '#/components/schemas/created'
example:
id: 8
201-created:
description: Created.
content:
application/json:
schema:
$ref: '#/components/schemas/created'
example:
id: 8
204-no-content:
description: No content.
400-bad-request:
description: Bad request.
content:
application/json:
schema:
$ref: '#/components/schemas/error'
example:
code: 400 Bad Request
message: Invalid request body.
401-unauthorized:
description: Unauthorized.
content:
application/json:
schema:
$ref: '#/components/schemas/error'
example:
code: 401 Unauthorized
message: API key is missing or invalid.
404-not-found:
description: The specified resource was not found.
content:
application/json:
schema:
$ref: '#/components/schemas/error'
example:
code: 404 Not Found
message: The specified resource was not found.
schemas:
server:
type: object
properties:
meta:
type: object
properties:
hostname:
type: string
description: The hostname.
example: keyhelp.example.com
ip_addresses:
type: array
items:
type: string
description: The IP addresses associated to the server.
example:
- 192.168.178.1
- 192.168.178.2
server_time:
type: string
format: date-time
description: The time and timezone as ISO-8601 string.
example: '2019-08-15T11:29:13+02:00'
uptime:
type: object
description: The uptime of the server.
properties:
days:
type: integer
example: 80
hours:
type: integer
example: 11
minutes:
type: integer
example: 37
seconds:
type: integer
example: 29
panel_version:
type: string
description: The file version of KeyHelp.
example: 19.3.1
panel_build:
type: integer
description: The build version of KeyHelp.
example: '1923'
api_version:
type: string
description: The supportet API version,
example: 1.0.15
api_docs:
type: string
description: The URL where you view the appropriate API documentation.
example: https://app.swaggerhub.com/apis-docs/keyhelp/api/1.0.15
keyhelp_pro:
type: boolean
description: Indicates whether the system has a valid KeyHelp Pro license.
example: true
operating_system:
type: object
properties:
label:
type: string
description: The OS version in long form.
example: Debian 12.0 (64-bit)
distribution:
type: string
description: The OS distribution name.
example: Debian
version:
type: string
description: The OS version string.
example: '10'
architecture:
type: string
description: The OS architecture.
example: 64-bit
end_of_life:
type: boolean
description: Indicates whether the OS has reached End-Of-Life status.
example: false
updates:
type: object
properties:
update_count:
type: integer
description: Indicates how many updates are available.
example: 12
security_update_count:
type: integer
description: Indicates how many updates are security updates.
example: 8
reboot_required:
type: integer
description: >-
Indicates if a reboot is required in order to complete a
previous update.
example: false
utilization:
type: object
properties:
process_count:
type: integer
description: The number of processes the server has currently running.
example: 171
emails_in_queue:
type: integer
description: The number of emails in the email queue.
example: 33
load:
type: object
properties:
minute_1:
type: number
description: The load average of the last 1 minute.
example: 0.4
minute_5:
type: number
description: The load average of the last 5 minutes.
example: 0.26
minute_15:
type: number
description: The load average of the last 15 minutes.
example: 0.15
cpu_count:
type: integer
description: The number of CPU cores.
example: 2
percent:
type: number
description: >-
The load of the last 1 minute with taken the number of CPU
cores in account.
example: 20
level:
type: string
description: A string expression of the "percent" value above.
example: low
disk_space:
type: object
description: Disk space usage of the primary file system.
properties:
free:
type: integer
description: The amount of free disk space in byte.
example: 100631449600
used:
type: integer
description: The amount of used disk space in byte.
example: 21352624128
total:
type: integer
description: The total amount of disk space in byte.
example: 74143424512
percent:
type: number
description: The disk space usage in percent.
example: 21.22
inodes:
type: object
description: Inode usage of the primary file system.
properties:
free:
type: integer
description: The amount of free inodes.
example: 6082335
used:
type: integer
description: The amount of used inodes.
example: 168161
total:
type: integer
description: The total amount of inodes.
example: 6250496
percent:
type: number
description: The inodes usage in percent.
example: 2.69
memory:
type: object
properties:
free:
type: integer
description: The amount of free memory in byte.
example: 8371269632
used:
type: integer
description: The amount of used memory in byte.
example: 1350742016
total:
type: integer
description: The total amount of memory in byte.
example: 7020527616
percent:
type: number
description: The memory usage in percent.
example: 16.14
swap:
type: object
properties:
free:
type: integer
description: The amount of free swap space in byte.
example: 4000313344
used:
type: integer
description: The amount of used swap space in byte.
example: 39919616
total:
type: integer
description: The total amount of swap space in byte.
example: 3960393728
percent:
type: number
description: The swap space usage in percent.
example: 10.53
resources:
type: object
properties:
admin_accounts:
type: integer
description: The number of admin accounts.
example: 1
client_accounts:
type: integer
description: The number of client accounts.
example: 94
domains:
type: integer
description: The number of main domains (including system domains).
example: 375
subdomains:
type: integer
description: The number subdomains..
example: 242
email_accounts:
type: integer
description: The number of email accounts.
example: 505
email_addresses:
type: integer
description: The number of email addresses.
example: 956
email_forwardings:
type: integer
description: The number of email forwardings.
example: 124
databases:
type: integer
description: The number of databases.
example: 124
ftp_users:
type: integer
description: The number of ftp users.
example: 121
scheduled_tasks:
type: integer
description: The number of scheduled tasks (cron jobs).
example: 4
consumed_disk_space:
type: integer
description: The amount of consumed disk space by client accounts in byte.
example: 265783313694
traffic:
type: integer
description: >-
The amount of traffic caused by client accounts in the current
month in byte .
example: 153008209920
components:
type: object
properties:
kernel:
type: string
description: The version of the Kernel.
example: 4.15.0-109-generic
apache:
type: string
description: The version of Apache.
example: 2.4.29
php:
type: string
description: The version of PHP.
example: 7.2.24
mariadb:
type: string
description: The version of MariaDB (only available if MariaDB is installed).
example: 10.1.44
mysql:
type: string
description: The version of MySQL (only available if MySQL is installed).
example: 5.7.31
proftpd:
type: string
description: The version of ProFTPD
example: 1.3.5e
dovecot:
type: string
description: The version of Dovecot.
example: 2.2.33.2
postfix:
type: string
description: The version of Postfix.
example: 3.3.0
additional_php_interpreters:
type: array
items:
type: object
properties:
version:
type: string
example: '7.4'
version_full:
type: string
example: 7.4.8
ports:
type: array
items:
type: object
properties:
service:
type: string
example: SSH
port:
type: integer
example: 22
protocol:
type: string
example: tcp
status:
type: string
example: online
ping:
type: object
properties:
response:
type: string
example: pong
login-url:
description: |
The URL to log in to an account.
type: object
properties:
url:
type: string
example: https://keyhelp.example.com/index.php?sso_request=...&sso_token=...
admin:
description: |
Representation of an admin account.
type: object
properties:
id:
type: integer
readOnly: true
description: The ID of this account.
example: 8
username:
type: string
description: The username.
example: keyadmin
language:
type: string
minLength: 2
maxLength: 5
description: >-
The language, either a two character code e.g. "de" or the more
specific e.g. "de_DE"
example: de
email:
type: string
format: email
description: The email address of the account.
example: me@example.com
is_main_admin:
type: boolean
description: The is main admin status of the client.
example: true
created_at:
type: string
format: date-time
readOnly: true
description: The creation date of the user as ISO-8601 string.
example: '2019-08-15T11:29:13+02:00'
password:
type: string
format: password
writeOnly: true
description: The password.
example: qwertz
password_hash:
type: string
writeOnly: true
description: A bcrypt password hash. Only available if turned on in settings.
example: $2y$10$fF3npQ.jS/KL8Nr6zecPke8IUsuB1oGXxY7w4aa..."
client:
description: |
Representation of a client account.
type: object
properties:
id:
type: integer
readOnly: true
description: The ID of this account.
example: 8
status:
type: integer
readOnly: true
example: 1
username:
type: string
description: The username.
example: alex
language:
type: string
minLength: 2
maxLength: 5
description: >-
The language, either a two character code e.g. "de" or the more
specific e.g. "de_DE"
example: de
email:
type: string
format: email
description: The email address of the account.
example: me@example.com
password:
type: string
format: password
writeOnly: true
description: The password.
example: qwertz
notes:
type: string
example: Any comments about this client account.
id_hosting_plan:
type: integer
writeOnly: true
description: The ID of the hosting plan when creating or updating a client.
example: 5
created_at:
type: string
format: date-time
readOnly: true
description: The creation date of the user as ISO-8601 string.
example: '2019-08-15T11:29:13+02:00'
document_root:
type: string
readOnly: true
description: The absolute path to the clients document root.
example: /home/users/alex/
is_suspended:
type: boolean
description: The supsended status of the client.
example: false
suspend_on:
type: string
format: date-time
description: >-
The date, when a user gets suspended.<br>The passed in value must be
parse-able by the PHP function strtotime(). Best choice are ISO
formats like "Y-m-d H:i:s", but "+30 days" are also possible.
example: null
delete_on:
type: string
format: date-time
description: >-
The date, when a user gets deleted.<br>The passed in value must be
parse-able by the PHP function strtotime(). Best choice are ISO
formats like "Y-m-d H:i:s", but "+30 days" are also possible.
example: null
send_login_credentials:
type: boolean
writeOnly: true
default: true
description: >-
Determine, if new login credentials should be sent to the clients
email address. Only takes affect when a new password was set /
generated.
example: true
create_system_domain:
type: boolean
writeOnly: true
default: true
description: >-
Determine, if a system domain should be created. Only takes affect
on creation of a new user.
example: true
skeleton:
deprecated: true
type: string
writeOnly: true
description: >
The name of the skeleton directory which should get copied into the
users www/ directory.
This property is marked as deprecated and should no longer be used.
example: wordpress
contact_data:
type: object
properties:
first_name:
type: string
description: The first name.
example: Alex
last_name:
type: string
description: The last name.
example: Mahr
company:
type: string
description: The company name.
example: Keyweb AG
telephone:
type: string
description: The telephone number.
example: 555-Nase
address:
type: string
description: The address.
example: Neuwerkstraße 45/46
city:
type: string
description: The city.
example: Erfurt
zip:
type: string
description: The zip code.
example: '99084'
state:
type: string
description: The state.
example: Thuringia
country:
type: string
minLength: 2
maxLength: 2
description: The alpha-2 country code (ISO-3166).
example: DE
client_id:
type: string
description: The client / customer number.
example: ID-12345
resource_limits:
type: object
readOnly: true
properties:
disk_space:
type: integer
example: 1048576000
files:
type: integer
example: 128000
traffic:
type: integer
example: -1
domains:
type: integer
example: 10
subdomains:
type: integer
example: 50
email_accounts:
type: integer
example: 20
email_addresses:
type: integer
example: -1
email_forwardings:
type: integer
example: 2
databases:
type: integer
example: 10
ftp_users:
type: integer
example: -1
scheduled_tasks:
type: integer
example: 4
permissions:
type: object
readOnly: true
properties:
ftp:
type: boolean
example: true
php:
type: boolean
example: true
perl:
type: boolean
example: false
ssh:
type: boolean
example: false
backup:
type: boolean
example: true
panel_access:
type: boolean
example: true
domain_security:
type: boolean
example: true
certificate_management:
type: boolean
example: true
file_manager:
type: boolean
example: true
dns_editor:
type: boolean
example: true
database_remote_access:
type: boolean
example: true
update_contact_data:
type: boolean
example: true
email_catchall:
type: boolean
example: true
delete_main_domain:
type: boolean
example: true
applications:
type: boolean
example: true
ssh_jail:
type: boolean
example: false
password_hash:
type: string
description: A bcrypt password hash. Only available if turned on in settings.
example: $2y$10$fF3npQ.jS/KL8Nr6zecPke8IUsuB1oGXxY7w4aa..."
password_hash_os:
type: string
description: A SHA-512 password hash. Only available if turned on in settings.
example: $6$rounds=100000$tn0.24Y/EWkV8gjA$VkYdo/1X23dW..."
client-stats:
description: The value "-1" for the "max" property means "unlimited".
type: object
properties:
disk_space:
type: object
properties:
value:
type: integer
example: 1320702444
max:
type: integer
example: 2147483648
files:
type: object
properties:
value:
type: integer
example: 94832
max:
type: integer
example: 3288472
traffic:
type: object
properties:
value:
type: integer
example: 15966540923
max:
type: integer
example: -1
domains:
type: object
properties:
value:
type: integer
example: 4
max:
type: integer
example: 10
subdomains:
type: object
properties:
value:
type: integer
example: 12
max:
type: integer
example: 20
email_accounts:
type: object
properties:
value:
type: integer
example: 8
max:
type: integer
example: 20
email_addresses:
type: object
properties:
value:
type: integer
example: 37
max:
type: integer
example: -1
email_forwardings:
type: object
properties:
value:
type: integer
example: 2
max:
type: integer
example: -1
databases:
type: object
properties:
value:
type: integer
example: 3
max:
type: integer
example: 5
ftp_users:
type: object
properties:
value:
type: integer
example: 1
max:
type: integer
example: 10
scheduled_tasks:
type: object
properties:
value:
type: integer
example: 1
max:
type: integer
example: 5
client-traffic:
type: object
properties:
http:
type: object
properties:
in:
type: integer
example: 423455656
out:
type: integer
example: 2343244
requests:
type: integer
example: 53456
ftp:
type: object
properties:
in:
type: integer
example: 3455262
out:
type: integer
example: 6634452
requests:
type: integer
example: 344
pop3:
type: object
properties:
in:
type: integer
example: 87686
out:
type: integer
example: 678886
requests:
type: integer
example: 4666
imap:
type: object
properties:
in:
type: integer
example: 58683684
out:
type: integer
example: 9879743
requests:
type: integer
example: 45373
smtp:
type: object
properties:
in:
type: integer
example: 34535
out:
type: integer
example: 756757
requests:
type: integer
example: 4536
hosting-plan:
description: |
Representation of a hosting plan.
The value "-1" for resource properties means "unlimited".
type: object
properties:
id:
type: integer
readOnly: true
example: 8
name:
type: string
example: Hosting Plus
resources:
type: object
properties:
disk_space:
type: integer
example: 1073741824
traffic:
type: integer
example: -1
domains:
type: integer
example: 10
subdomains:
type: integer
example: 50
email_accounts:
type: integer
example: 20
email_addresses:
type: integer
example: -1
email_forwardings:
type: integer
example: 10
databases:
type: integer
example: 10
ftp_users:
type: integer
example: -1
scheduled_tasks:
type: integer
example: 4
permissions:
type: object
properties:
ftp:
type: boolean
example: true
php:
type: boolean
example: true
perl:
type: boolean
example: false
ssh:
type: boolean
example: false
backup:
type: boolean
example: true
panel_access:
type: boolean
example: true
domain_security:
type: boolean
example: true
certificate_management:
type: boolean
example: true
file_manager:
type: boolean
example: true
dns_editor:
type: boolean
example: true
database_remote_access:
type: boolean
example: true
update_contact_data:
type: boolean
example: true
change_personal_data:
deprecated: true
type: boolean
example: true
description: >
This property is marked as deprecated and should no longer be
used.<br>
Use 'update_contact_data' instead.
email_catchall:
type: boolean
example: true
delete_main_domain:
type: boolean
example: true
applications:
type: boolean
example: true
ssh_jail:
type: boolean
example: false
php:
type: object
properties:
memory_limit:
type: string
example: 256M
max_execution_time:
type: integer
example: 60
post_max_size:
type: string
example: 72M
upload_max_filesize:
type: string
example: 64M
open_basedir:
type: string
example: '##DOCROOT##/www:##DOCROOT##/files:##DOCROOT##/tmp'
disable_functions:
type: string
example: exec, system, shell_exec, passthru
extra_directives_immutable:
type: string
example: date.timezone = "US/Central"
extra_directives_mutable:
type: string
example: max_execution_time = "60"
additional_settings:
deprecated: true
type: boolean
example: date.timezone = "US/Central"
description: >
This property is marked as deprecated and should no longer be used.<br>
Use 'extra_directives_immutable' / 'extra_directives_mutable' instead.
php_fpm:
type: object
properties:
pm:
type: string
enum:
- static
- ondemand
- dynamic
example: ondemand
max_children:
type: integer
example: 3
max_requests:
type: integer
example: 0
min_spare_servers:
type: integer
example: null
max_spare_servers:
type: integer
example: null
status:
type: boolean
example: true
status_ip_restriction:
type: string
example: 192.168.178.1
domain:
description: |
Representation of a domain.
type: object
properties:
id:
type: integer
readOnly: true
description: The ID of the domain.
example: 8
id_user:
type: integer
description: >-
The user ID of the domain. This field is required, when adding a new
domain.
example: 4
id_parent_domain:
type: integer
description: >-
The ID of the parent domain, or 0 when it is a main domain.<br>Needs
to be specified when you want to create subdomains.
example: 0
status:
type: integer
readOnly: true
example: 1
domain:
type: string
description: The ASCII representation of the domain.
example: example.com
domain_utf8:
type: string
readOnly: true
description: The UTF-8 representation of the domain.
example: example.com
created_at:
type: string
format: date-time
readOnly: true
example: '2019-08-15T11:29:13+02:00'
php_version:
type: string
description: >-
If empty, the domain uses the system php version. If set, the domain
uses one of the installed additional php interpreters.
example: ''
traffic:
type: integer
description: >-
The amount of traffic (HTTP, POP3, IMAP, SMTP) this domain generated
in the current month.
example: 32434624
is_disabled:
type: boolean
example: false
delete_on:
type: string
format: date-time
example: '2019-08-15T11:29:13+02:00'
dkim_selector:
type: string
example: default
dkim_record:
type: string
readOnly: true
example: >-
default._domainkey IN TXT ( "v=DKIM1; k=rsa; s=email; " "...DKIM
KEY..." )
dkim_txt_record:
deprecated: true
type: string
readOnly: true
example: >-
default._domainkey IN TXT ( "v=DKIM1; k=rsa; s=email; " "...DKIM
KEY..." )
description: >
This property is marked as deprecated and should no longer be
used.<br>
Use 'dkim_record' instead.
is_custom_dns:
type: boolean
readOnly: true
example: false
is_dns_disabled:
type: boolean
example: false
is_subdomain:
type: boolean
readOnly: true
example: false
is_system_domain:
type: boolean
readOnly: true
example: false
is_email_domain:
type: boolean
example: true
is_email_sending_only:
type: boolean
example: false
create_www_subdomain:
type: boolean
writeOnly: true
default: true
description: Only takes affect when creating a new user.
example: true
skeleton:
deprecated: true
type: string
writeOnly: true
description: >
The name of the skeleton directory which should get copied into the
users www/ directory.
Only works if the directory does not already exists.
This property is marked as deprecated and should no longer be used.
example: wordpress
target:
type: object
properties:
target:
type: string
description: >
Either a relative path to target folder (relative from clients
/www/ folder), or an URL.<br>
When specifying a URL, they have to start with "http://" or
"https://."
example: https://www.keyhelp.de
is_forwarding:
type: boolean
readOnly: true
example: true
forwarding_type:
type: integer
enum:
- 301
- 302
security:
type: object
properties:
id_certificate:
type: integer
description: >
The certificate ID. You can only use either a certificate, the "lets_encrypt" option or none of both.<br>
You can only assign certificates with at least "private_key" and "certificate" component'
example: 0
lets_encrypt:
type: boolean
description: >-
Determin if the domain should use a Lets Encrypt certificate. You can only use either a certificate, the "lets_encrypt" option or none of both.
example: true
is_prefer_https:
type: boolean
description: >-
Prefer HTTPS instead of HTTP. If an SSL/TLS certificate is used, this setting will perform an automatic forwarding to HTTPS when the domian is accessed via HTTP.
example: true
force_https:
deprecated: true
type: boolean
description: >-
This property is marked as deprecated and should no longer be used.<br>
Use 'is_prefer_https' instead.
example: true
is_hsts:
type: boolean
example: true
hsts_max_age:
type: integer
description: Max-Age value in seconds
example: 10368000
hsts_include:
type: boolean
example: true
hsts_preload:
type: boolean
example: true
apache:
type: object
properties:
http_directives:
type: string
example: '# My custom HTTP directives'
https_directives:
type: string
example: '# My custom HTTPS directives'
dns:
description: |
Representation of DNS settings of a Domain.
type: object
properties:
is_custom_dns:
type: boolean
readOnly: true
example: false
is_dns_disabled:
type: boolean
example: false
dkim_record:
type: string
readOnly: true
example: >-
default._domainkey IN TXT ( "v=DKIM1; k=rsa; s=email; " "...DKIM
KEY..." )
dkim_txt_record:
deprecated: true
type: string
readOnly: true
example: >-
default._domainkey IN TXT ( "v=DKIM1; k=rsa; s=email; " "...DKIM
KEY..." )
description: >
This property is marked as deprecated and should no longer be
used.<br>
Use 'dkim_record' instead.
records:
type: object
properties:
soa:
type: object
properties:
ttl:
type: integer
default: 86400
example: 86400
primary_ns:
type: string
default: Default primary name server of the system
example: ns.example.com.
rname:
type: string
default: System email
example: root.example.com.
refresh:
type: integer
default: 14400
example: 14400
retry:
type: integer
default: 1800
example: 1800
expire:
type: integer
default: 604800
example: 604800
minimum:
type: integer
default: 3600
example: 3600
other:
type: array
items:
type: object
properties:
host:
type: string
example: '@'
ttl:
type: integer
default: 86400
example: 86400
type:
type: string
example: A
value:
type: string
example: 192.168.178.1
certificate:
description: |
Representation of a certificate.
type: object
properties:
id:
type: integer
readOnly: true
example: 8
id_user:
type: integer
description: >-
The ID of the associated client, or 0 / null if there is no client
associated to the certificate.
example: 2
name:
type: string
example: Homepage
secured_domains:
type: array
items:
type: string
readOnly: true
example:
- example.com
- www.example.com
valid_till:
type: string
format: date-time
readOnly: true
description: >-
The date, when the certificate is no longer valid as ISO-8601
string.
example: '2027-08-15T21:06:18+02:00'
issuer:
type: string
readOnly: true
example: AlphaSSL CA - SHA256 - G2 / GlobalSign nv-sa
components:
type: object
properties:
private_key:
type: string
example: '-----BEGIN PRIVATE KEY----- ... -----END PRIVATE KEY-----'
csr:
type: string
example: '-----BEGIN CSR----- ... -----END CSR-----'
readOnly: true
certificate':
type: string
example: '-----BEGIN CERTIFICATE----- ... -----END CERTIFICATE-----'
ca_certificate:
type: string
example: '-----BEGIN CERTIFICATE----- ... -----END CERTIFICATE-----'
usage:
type: object
readOnly: true
properties:
domain_count:
type: integer
example: 2
server_service:
type: boolean
example: true
email:
description: |
Representation of an email account.
type: object
properties:
id:
type: integer
readOnly: true
example: 8
id_user:
type: integer
description: >-
The user ID of the email account. This field is required, when
adding a new email account.
example: 3
id_domain:
type: integer
readOnly: true
example: 31
status:
type: integer
readOnly: true
example: 1
email:
type: string
format: email
description: The ASCII representation of the email address.
example: info@example.com
email_utf8:
type: string
format: email
readOnly: true
description: The UTF-8 representation of the email address.
example: info@example.com
password:
type: string
format: password
writeOnly: true
example: qwertz
description:
type: string
example: Description for this email account.
size:
type: integer
example: 579712587
readOnly: true
description: Mailbox size in byte
max_size:
type: integer
example: 1073741824
description: Maximum mailbox size in byte
catch_all:
type: boolean
example: false
store_forwarded_emails:
type: boolean
example: true
aliases:
type: array
items:
type: string
description: A list of all alias addresses in ASCII representation.
example:
- contact@example.com
- john.doe@example.com
- lemmy@xn--motrhead-p4a.com
aliases_utf8:
type: array
readOnly: true
items:
type: string
description: A list of all alias addresses in UTF-8 representation.
example:
- contact@example.com
- john.doe@example.com
- lemmy@motörhead.com
forwardings:
type: array
items:
type: string
description: A list of all forwarding addresses in ASCII representation.
example:
- forward@xn--motrhead-p4a.com
forwardings_utf8:
type: array
readOnly: true
items:
type: string
description: A list of all forwarding addresses in UTF-8 representation.
example:
- forward@motörhead.com
protection:
type: object
properties:
check_spam:
type: boolean
description: Specify whether mails for this email account should be checked for spam.
example: true
check_virus:
type: boolean
description: Specify whether mails for this email account should be checked for viruses.
example: true
spam_tag_score:
type: number
description: Only Rspamd systemd | Emails with a score exceeding this threshold will be classified as spam. The value 0 means, use the server default settings. If defined spam_rewrite_subject must also be defined.
example: 6.0
spam_reject_score:
type: number
description: Only Rspamd systemd | Emails with a score exceeding this threshold will be rejected. The value 0 means, use the server default settings. If defined spam_rewrite_subject must also be defined.
example: 15
spam_rewrite_subject:
type: boolean
description: Only Rspamd systemd | If spam is found, the subject of the email is tagged with ***SPAM***.
example: 4.1
spam_score:
type: number
description: Only Amavis systemd
example: 4.1
expunge_junk:
type: integer
example: 100
expunge_trash:
type: integer
example: null
password_hash:
type: string
description: >-
A BCRYPT/SHA-512 password hash. Only available if turned on in
settings.
example: $2y$10$nAad.Rrq3LocWPgj2C9X8O7oIL/K4Q3g7PPC..."
database:
description: |
Representation of a database and the corresponding database user.
type: object
properties:
id:
type: integer
readOnly: true
example: 8
id_user:
type: integer
description: >-
The user ID of the database. This field is required, when adding a
new database.
example: 2
database_name:
type: string
example: alex_db1
database_username:
type: string
example: alex_db1
password:
type: string
format: password
writeOnly: true
example: qwertz
description:
type: string
example: This is the database for my Wordpress installation.
size:
type: integer
description: Database size in byte.
example: 114688
readOnly: true
remote_hosts:
type: array
items:
type: string
example:
- 93.152.27.25
- 120.237.75.141
password_hash:
type: string
description: >-
A MariaDB/MySQL password hash. Only available if turned on in
settings.
example: '*3B501FC38B83F25B219D020656A7C104960C33E7'
ftp-user:
description: |
Representation of a FTP user.
type: object
properties:
id:
type: integer
readOnly: true
example: 8
id_user:
type: integer
description: >-
The user ID of the FTP user. This field is required, when adding a
new FTP user.
example: 2
status:
type: integer
readOnly: true
example: 1
username:
type: string
example: alex_ftp1
description:
type: string
example: This user can access my images.
home_directory:
type: string
description: >-
The home directory of the FTP user, beginning with either "/www/" or
"/files".
example: /www/website/images/
password:
type: string
format: password
writeOnly: true
example: qwertz
password_hash:
type: string
description: >-
A BCRYPT/SHA-512 password hash. Only available if turned on in
settings.
example: $2y$10$nAad.Rrq3LocWPgj2C9X8O7oIL/K4Q3g7PPC...
scheduled-task:
description: |
Representation of a scheduled task.
type: object
properties:
id:
type: integer
readOnly: true
example: 8
id_user:
type: integer
description: >-
The ID of the associated client, or 0 / null if there is no client
associated to the scheduled task - in this case, the scheduled task
will run in root context.
example: 2
status:
type: integer
readOnly: true
example: 1
type:
type: string
example: php
description: >-
Available types are 'exec' - if a normal CLI command should be
executed, 'php' if a PHP script should be executed, 'http' if a URL
should be called.
php_interpreter:
type: string
description: >-
Used when type = 'php'. Can either be null, if the default PHP
interpreter of the operating system should be used, or the version
of an installed additional PHP interpreter.
example: '8.0'
command:
type: string
example: /home/users/alex/www/cleanup.php
notify:
type: string
description: 'One of the following strings: ''never'', ''error'', ''always''.'
example: error
email:
type: string
format: email
description: Used when notify is set to 'error' or 'always'.
example: info@keyhelp.de
description:
type: string
example: Perform cleanup tasks.
schedule:
type: object
properties:
minute:
type: string
example: '10'
hour:
type: string
example: '*/6'
day_of_month:
type: string
example: '*'
month:
type: string
example: '*'
day_of_week:
type: string
example: '*'
directory-protection:
description: |
Representation of a directory protection.
type: object
properties:
id:
type: integer
readOnly: true
example: 8
id_user:
type: integer
description: >-
The user ID of the directory protection. This field is required,
when adding a new directory protection.
example: 2
status:
type: integer
readOnly: true
example: 1
path:
type: string
description: >-
The protected directory path. This path is relative to the users
/www/ directory.
example: /private/holiday_pictures/
exceptions:
type: array
items:
type: string
description: >-
Directories and URL paths, for which the directory protection should
not apply.
example:
- /intern/api
auth_name:
type: string
example: This is a restricted area
username:
type: string
example: alex
password:
type: string
format: password
writeOnly: true
example: qwertz
password_hash:
type: string
description: An APR-1 password hash. Only available if turned on in settings.
example: $apr1$npcurdzf$2xYm6oo0kB4Q.hpNUw1/S0
created:
type: object
properties:
id:
type: integer
error:
type: object
properties:
code:
type: string
message:
type: string
required:
- code
- message