bindAPI/public/openapi/openapi.keyhelp.json

6672 lines
168 KiB
JSON
Raw Permalink Normal View History

2022-02-05 20:26:32 +01:00
{
"openapi": "3.0.2",
"info": {
"title": "KeyHelp RESTful API",
"version": "2.2",
"description": "Provides an interface to a server managed by the KeyHelp server administration tool.\n\nThere latest version of this documentation is available <a href=\"https&colon;//app.swaggerhub.com/apis-docs/keyhelp/api/\" target=\"_blank\">here</a>.\n\n## URL\n\n* To communicate with the API, you need to call a specific URL which looks like the this&colon;<br>\n ```\n https://<hostname>/api/v2/<API endpoint>\n ```\n ```\n https://<IP address>/api/v2/<API endpoint>\n ```\n* Have a look below to see all available API endoints.\n\n\n## Authentication\n\n* You need to define API keys inside of the KeyHelp user interface (*Admin area* -> *Configuration* -> *API*).<br>\n Each API key should be restricted to certain IP / IP range.\n* Pass the API key with each request using the `X-API-Key` header field.\n\n\n## Request format\n\n* Some requests require you to send data inside of the request body.<br>\n These data must be sent as `application/json`.\n\n## Response format\n\n* Use the `ACCEPT` header field to specify your desired response mime type.\n* The following response formats are supported&colon;\n - `application/json` (default)\n - `application/xml`\n - `text/yaml`\n\n## Hints\n\n* The API is not enabled by default. You first have to turn it on via KeyHelp user interface.<br>\n (*Admin area* -> *Configuration* -> *API*)\n\n* 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>\n (*Admin area* -> *Configuration* -> *API* -> *Options*)\n\n* You can turn on the `password_hash` field in API settings, and so read and set the password hash of a given element.\n 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.\n\n* 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.\n\n* Some object schemas contain a read-only \"status\" field. The meaning of these values is as follows&colon;<br>\n 0 = \"unknown\", 1 = \"okay\", 2 = \"error\", 3 = \"config_new\", 4 = \"config_update\"\n\n## Shorthand byte values\n\n* When specifing byte values, you can also use a shorthand notation.\n* Available options are&colon; K (kilobyte), M (megabyte), G (gigabyte), T (terabyte), P (petabyte)\n* One kilobyte is described as 1024 byte, 1M equals to 1048576 bytes\n* Do not use decimals, only integers!\n\n<br>\n\n## HTTP status code summary\n| Code | Description |\n| --- | --- |\n| **200 - OK** | Everything worked as expected. |\n| **201 - Created** | The ressource was successfully created. |\n| **204 - No Content** | The response does not contain any data. Used on delete operations. |\n| **400 - Bad Request** | The request was unacceptable, due to an malformed request, invalid parameter value or a missing required parameter. |\n| **401 - Unauthorized** | Invalid API key provided |\n| **403 - Forbidden** | API access is denied. |\n| **404 - Not Found** | The ressouce was not found / The requested endpoint was not found. |\n| **405 - Method Not Allowed** | The HTTP method for the requested endpoint is not allowed. |\n| **406 - Not Acceptable** | Invalid Accept header value. Mime type not supported. |\n| **5xx - Server error** | Something went wrong on KeyHelp's end. |\n\n<br>\n\n## API version upgrade guide\n\n #### Breaking changes from `v1` to `v2`\n 1) `[GET] /certificates/`&colon; Output format changed for field `components`.\n 2) `[PUT/POST] /certificates/`&colon; Certificate components are now specified within the `components` field.\n\n<br>\n",
"contact": {
"name": "Alexander Mahr (KeyHelp Developer)",
"email": "info@keyhelp.de",
"url": "https://www.keyhelp.de/en"
}
},
"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.\n\nIf performance is a concern, you can use the query parameters,\nto query only for the information you need.\n",
"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"
}
],
"responses": {
"200": {
"$ref": "#/components/responses/server"
},
"401": {
"$ref": "#/components/responses/401-unauthorized"
}
}
}
},
"/ping": {
"get": {
"tags": [
"Server"
],
"summary": "Returning pong.",
"description": "Returns \"pong\".\n\nCan be used to check API or server availability.\n",
"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.\n\nSecurity notes&colon;<br>\nThe generated URL has a validity period of 60 minutes.<br>\nThe login is protected by a brute force protection.\n",
"responses": {
"200": {
"$ref": "#/components/responses/login-url"
},
"401": {
"$ref": "#/components/responses/401-unauthorized"
}
}
}
},
"/domains": {
"get": {
"tags": [
"Domains"
],
"summary": "Listing all domains.",
"description": "Returns a list of all domains on this server.\n\nYou can use the following filter parameter values to filter the results.\n* main_domains\n* subdomains\n* system_domains\n\nYou can use the following sort parameter values to sort the results.\n* id (default)\n* domain\n* domain_utf8\n",
"parameters": [
{
"$ref": "#/components/parameters/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.\n",
"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.\n",
"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.\n",
"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.\n",
"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.\n",
"responses": {
"200": {
"$ref": "#/components/responses/domain"
},
"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.\n\nOnly IDs of main domains are allowed, IDs of subdomains will result in a 404 error.\n\nThe placeholder `<DKIM_RECORD_VALUE>` in the `value` field of a record will be replace with the actual DKIM record.\n",
"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.\n\nOnly IDs of main domains are allowed, IDs of subdomains will result in a 404 error.\n\nAttention, when inserting custom DNS records, you have to specify all records not just the one you want to update.\n\nIf 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.\n* If `is_dns_disabled` is set to `true` -> DNS will be disabled\n\n* If `is_dns_disabled` is set to `false` -> DNS will be enabled with the default DNS settings\n\nIf 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.\n\nThe placeholder `<DKIM_RECORD_VALUE>` in the `value` field of a record will be replace with the actual DKIM record.\n",
"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&colon;\n\n* A previously disabled DNS will be activated.\n* The SOA and all other DNS records are reset to their default values.\n",
"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.\n\nYou can use the following sort parameter values to sort the results.\n* id (default)\n* name\n",
"parameters": [
{
"$ref": "#/components/parameters/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.\n",
"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.\n",
"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.\n\nSpecify only the fields, you want to update.\n",
"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.\n",
"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/hosting-plan-name"
}
],
"get": {
"tags": [
"Certificates"
],
"summary": "Returning a single certificate.",
"description": "Returns information of a single certificate specified by its name.\n",
"responses": {
"200": {
"$ref": "#/components/responses/certificate"
},
"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.\n\nYou can use the following sort parameter values to sort the results.\n* id (default)\n* email\n* email_utf8\n",
"parameters": [
{
"$ref": "#/components/parameters/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.\n\nIf the following properties accepts punycode and UTF-8 domain names&colon;\n* email\n* aliases\n* forwardings\n\nIf the following properties are empty / not set, they are auto-generated&colon;\n* password\n\nIf the following properties are auto-generated, they are part of the response&colon;\n* password\n",
"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.\n",
"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.\n\nSpecify only the fields, you want to update.\n\nIf the following properties accepts punycode and UTF-8 domain names&colon;\n* aliases\n* forwardings\n\nIf the following properties are part of the request but empty / null, they are auto-generated&colon;\n* password\n\nIf the following properties are auto-generated, they are part of the response&colon;\n* password\n",
"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.\n",
"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.\n",
"responses": {
"200": {
"$ref": "#/components/responses/email"
},
"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.\n\nYou can use the following sort parameter values to sort the results.\n* id (default)\n* database_name\n* database_username\n",
"parameters": [
{
"$ref": "#/components/parameters/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.\n\nIf the following properties are empty / not set, they are auto-generated&colon;\n* database_name and database_username\n* password\n\nIf the following properties are auto-generated, they are part of the response&colon;\n* database_name and database_username\n* password\n",
"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.\n",
"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.\n\nSpecify only the fields, you want to update.\n\nIf the following properties are part of the request but empty / null, they are auto-generated&colon;\n* password\n\nIf the following properties are auto-generated, they are part of the response&colon;\n* password\n",
"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.\n",
"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.\n",
"responses": {
"200": {
"$ref": "#/components/responses/database"
},
"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.\n\nYou can use the following sort parameter values to sort the results.\n* id (default)\n* username\n",
"parameters": [
{
"$ref": "#/components/parameters/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.\n\n**Please note**, to create a new FTP user, it is required that the corresponding (system) user account is fully set up.\nOtherwise you will receive the **400 Bad Request** error&colon;<br>\n**Invalid property data for&colon; 'uid', 'gid'**\n\nIf the following properties are empty / not set, they are auto-generated&colon;\n* username\n* password\n* home_directory (defaults to /www/)\n\nIf the following properties are auto-generated, they are part of the response&colon;\n* username\n* password\n",
"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.\n",
"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.\n\nSpecify only the fields, you want to update.\n\nIf the following properties are part of the request but empty / null, they are auto-generated&colon;\n* password\n\nIf the following properties are auto-generated, they are part of the response&colon;\n* password\n",
"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.\n",
"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.\n",
"responses": {
"200": {
"$ref": "#/components/responses/ftp-user"
},
"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.\n\nYou can use the following sort parameter values to sort the results.\n* id (default)\n* type\n",
"parameters": [
{
"$ref": "#/components/parameters/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.\n",
"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.\n",
"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.\n\nSpecify only the fields, you want to update. Read the exception below!\n\nATTENTION! When updating the schedule settings, all missing schedule fields in the request will default to `*`.\n\nAs an example, imagine you have a scheduled task with the following settings&colon;<br>\n `minutes = 10`, `hour = 4`, `day_of_week = *`, `month = *`, `day_of_month = 1`\n\nIf 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.\n\nIf you don't do it, and only set the `minutes`, all other values will default to `*`. You would end up with the following&colon;<br>\n `minutes` = 10, `hour = *`, `day_of_week = *`, `month = *`, `day_of_month = *`\n",
"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.\n",
"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.\n\nYou can use the following sort parameter values to sort the results.\n* id (default)\n* auth_name\n* username\n",
"parameters": [
{
"$ref": "#/components/parameters/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.\n\nIf the following properties are empty / not set, they are auto-generated&colon;\n* password\n* path (defaults to /, which corresponds to the user's /www/ directory)\n\nIf the following properties are auto-generated, they are part of the response&colon;\n* password\n",
"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.\n",
"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.\n\nSpecify only the fields, you want to update.\n\nIf the following properties are part of the request but empty / null, they are auto-generated&colon;\n* password\n",
"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.\n",
"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": {
"sort": {
"name": "sort",
"in": "query",
"description": "The property you want to sort by.",
"required": false,
"schema": {
"type": "string"
}
},
"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
}
},
"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"
}
},
"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-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-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-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.\n",
"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"
}
},
"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"
}
},
"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"
}
},
"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-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-task-id": {
"name": "id",
"in": "path",
"description": "Numeric ID of the scheduled task to get.",
"required": true,
"schema": {
"type": "integer",
"minimum": 1
}
},
"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,
"force_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"
}
}
}
},
"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": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
}
},
"required": [
"code",
"message#"
]
}
}
},
{
"openapi": "3.0.2",
"info": {
"title": "KeyHelp RESTful API",
"version": "2.2",
"description": "Provides an interface to a server managed by the KeyHelp server administration tool.\n\nThere latest version of this documentation is available <a href=\"https&colon;//app.swaggerhub.com/apis-docs/keyhelp/api/\" target=\"_blank\">here</a>.\n\n## URL\n\n* To communicate with the API, you need to call a specific URL which looks like the this&colon;<br>\n ```\n https://<hostname>/api/v2/<API endpoint>\n ```\n ```\n https://<IP address>/api/v2/<API endpoint>\n ```\n* Have a look below to see all available API endoints.\n\n\n## Authentication\n\n* You need to define API keys inside of the KeyHelp user interface (*Admin area* -> *Configuration* -> *API*).<br>\n Each API key should be restricted to certain IP / IP range.\n* Pass the API key with each request using the `X-API-Key` header field.\n\n\n## Request format\n\n* Some requests require you to send data inside of the request body.<br>\n These data must be sent as `application/json`.\n\n## Response format\n\n* Use the `ACCEPT` header field to specify your desired response mime type.\n* The following response formats are supported&colon;\n - `application/json` (default)\n - `application/xml`\n - `text/yaml`\n\n## Hints\n\n* The API is not enabled by default. You first have to turn it on via KeyHelp user interface.<br>\n (*Admin area* -> *Configuration* -> *API*)\n\n* 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>\n (*Admin area* -> *Configuration* -> *API* -> *Options*)\n\n* You can turn on the `password_hash` field in API settings, and so read and set the password hash of a given element.\n 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.\n\n* 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.\n\n* Some object schemas contain a read-only \"status\" field. The meaning of these values is as follows&colon;<br>\n 0 = \"unknown\", 1 = \"okay\", 2 = \"error\", 3 = \"config_new\", 4 = \"config_update\"\n\n## Shorthand byte values\n\n* When specifing byte values, you can also use a shorthand notation.\n* Available options are&colon; K (kilobyte), M (megabyte), G (gigabyte), T (terabyte), P (petabyte)\n* One kilobyte is described as 1024 byte, 1M equals to 1048576 bytes\n* Do not use decimals, only integers!\n\n<br>\n\n## HTTP status code summary\n| Code | Description |\n| --- | --- |\n| **200 - OK** | Everything worked as expected. |\n| **201 - Created** | The ressource was successfully created. |\n| **204 - No Content** | The response does not contain any data. Used on delete operations. |\n| **400 - Bad Request** | The request was unacceptable, due to an malformed request, invalid parameter value or a missing required parameter. |\n| **401 - Unauthorized** | Invalid API key provided |\n| **403 - Forbidden** | API access is denied. |\n| **404 - Not Found** | The ressouce was not found / The requested endpoint was not found. |\n| **405 - Method Not Allowed** | The HTTP method for the requested endpoint is not allowed. |\n| **406 - Not Acceptable** | Invalid Accept header value. Mime type not supported. |\n| **5xx - Server error** | Something went wrong on KeyHelp's end. |\n\n<br>\n\n## API version upgrade guide\n\n #### Breaking changes from `v1` to `v2`\n 1) `[GET] /certificates/`&colon; Output format changed for field `components`.\n 2) `[PUT/POST] /certificates/`&colon; Certificate components are now specified within the `components` field.\n\n<br>\n",
"contact": {
"name": "Alexander Mahr (KeyHelp Developer)",
"email": "info@keyhelp.de",
"url": "https://www.keyhelp.de/en"
}
},
"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.\n\nIf performance is a concern, you can use the query parameters,\nto query only for the information you need.\n",
"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"
}
],
"responses": {
"200": {
"$ref": "#/components/responses/server"
},
"401": {
"$ref": "#/components/responses/401-unauthorized"
}
}
}
},
"/ping": {
"get": {
"tags": [
"Server"
],
"summary": "Returning pong.",
"description": "Returns \"pong\".\n\nCan be used to check API or server availability.\n",
"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.\n\nSecurity notes&colon;<br>\nThe generated URL has a validity period of 60 minutes.<br>\nThe login is protected by a brute force protection.\n",
"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.\n\nYou can use the following sort parameter values to sort the results.\n* id (default)\n* username\n",
"parameters": [
{
"$ref": "#/components/parameters/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.\n\nIf the following properties are empty / not set, they are auto-generated&colon;\n* password\n\nIf the following properties are auto-generated, they are part of the response&colon;\n* password\n",
"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 client.",
"description": "Returns account details of a single admin determined by its ID.\n",
"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.\n\nSpecify only the fields, you want to update.\n\nIf the following properties are part of the request but empty / null, they are auto-generated&colon;\n* password\n\nIf the following properties are auto-generated, they are part of the response&colon;\n* password\n",
"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.\n",
"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.\n",
"responses": {
"200": {
"$ref": "#/components/responses/client"
},
"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.\n\nYou can use the following sort parameter values to sort the results.\n* id (default)\n* username\n",
"parameters": [
{
"$ref": "#/components/parameters/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.\n\nTo specify its account features, you should use a hosting plan,\notherwise it is created with the default hosting plan.\nUse the hosting plan endpoint to gather the information you need.\n\nIf the following properties are empty / not set, they are auto-generated&colon;\n* password\n\nIf the following properties are auto-generated, they are part of the response&colon;\n* password\n",
"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.\n",
"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.\n\nSpecify only the fields, you want to update.\n\nIf the following properties are part of the request but empty / null, they are auto-generated&colon;\n* password\n\nIf the following properties are auto-generated, they are part of the response&colon;\n* password\n",
"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.\n",
"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.\n\nProperties are&colon;\n* domain items\n* certificate items\n* email items\n* database items\n* ftp user items\n* scheduled task items\n* directory protection items\n\nIf performance is a concern, you can use the query parameters,\nto query only for the information you need.\n",
"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\ntheir usage.\n",
"responses": {
"200": {
"$ref": "#/components/responses/client-stats"
},
"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.\n",
"responses": {
"200": {
"$ref": "#/components/responses/client"
},
"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.\n\nYou can use the following sort parameter values to sort the results.\n* id (default)\n* name\n",
"parameters": [
{
"$ref": "#/components/parameters/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.\n\nYou do not have to specify all available fields. Only the `name` field is required.<br>\nOther fields are filled with default values, as it would be within the KeyHelp UI.\n",
"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.\n",
"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.\n\nPlease note that a hosting plan only serves as a template for client accounts.<br>\nClient accounts are not automatically updated when a hosting plan is updated.\n",
"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.\n",
"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}": {
"get": {
"tags": [
"Hosting plans"
],
"summary": "Returning a single hosting plan.",
"description": "Returns the features of a single hosting plan specified by its name.\n",
"parameters": [
{
"$ref": "#/components/parameters/hosting-plan-name"
}
],
"responses": {
"200": {
"$ref": "#/components/responses/hosting-plan"
},
"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.\n\nYou can use the following filter parameter values to filter the results.\n* main_domains\n* subdomains\n* system_domains\n\nYou can use the following sort parameter values to sort the results.\n* id (default)\n* domain\n* domain_utf8\n",
"parameters": [
{
"$ref": "#/components/parameters/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.\n",
"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.\n",
"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.\n",
"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.\n",
"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.\n",
"responses": {
"200": {
"$ref": "#/components/responses/domain"
},
"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.\n\nOnly IDs of main domains are allowed, IDs of subdomains will result in a 404 error.\n\nThe placeholder `<DKIM_RECORD_VALUE>` in the `value` field of a record will be replace with the actual DKIM record.\n",
"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.\n\nOnly IDs of main domains are allowed, IDs of subdomains will result in a 404 error.\n\nAttention, when inserting custom DNS records, you have to specify all records not just the one you want to update.\n\nIf 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.\n* If `is_dns_disabled` is set to `true` -> DNS will be disabled\n\n* If `is_dns_disabled` is set to `false` -> DNS will be enabled with the default DNS settings\n\nIf 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.\n\nThe placeholder `<DKIM_RECORD_VALUE>` in the `value` field of a record will be replace with the actual DKIM record.\n",
"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&colon;\n\n* A previously disabled DNS will be activated.\n* The SOA and all other DNS records are reset to their default values.\n",
"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.\n\nYou can use the following sort parameter values to sort the results.\n* id (default)\n* name\n",
"parameters": [
{
"$ref": "#/components/parameters/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.\n",
"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.\n",
"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.\n\nSpecify only the fields, you want to update.\n",
"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.\n",
"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/hosting-plan-name"
}
],
"get": {
"tags": [
"Certificates"
],
"summary": "Returning a single certificate.",
"description": "Returns information of a single certificate specified by its name.\n",
"responses": {
"200": {
"$ref": "#/components/responses/certificate"
},
"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.\n\nYou can use the following sort parameter values to sort the results.\n* id (default)\n* email\n* email_utf8\n",
"parameters": [
{
"$ref": "#/components/parameters/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.\n\nIf the following properties accepts punycode and UTF-8 domain names&colon;\n* email\n* aliases\n* forwardings\n\nIf the following properties are empty / not set, they are auto-generated&colon;\n* password\n\nIf the following properties are auto-generated, they are part of the response&colon;\n* password\n",
"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.\n",
"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.\n\nSpecify only the fields, you want to update.\n\nIf the following properties accepts punycode and UTF-8 domain names&colon;\n* aliases\n* forwardings\n\nIf the following properties are part of the request but empty / null, they are auto-generated&colon;\n* password\n\nIf the following properties are auto-generated, they are part of the response&colon;\n* password\n",
"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.\n",
"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.\n",
"responses": {
"200": {
"$ref": "#/components/responses/email"
},
"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.\n\nYou can use the following sort parameter values to sort the results.\n* id (default)\n* database_name\n* database_username\n",
"parameters": [
{
"$ref": "#/components/parameters/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.\n\nIf the following properties are empty / not set, they are auto-generated&colon;\n* database_name and database_username\n* password\n\nIf the following properties are auto-generated, they are part of the response&colon;\n* database_name and database_username\n* password\n",
"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.\n",
"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.\n\nSpecify only the fields, you want to update.\n\nIf the following properties are part of the request but empty / null, they are auto-generated&colon;\n* password\n\nIf the following properties are auto-generated, they are part of the response&colon;\n* password\n",
"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.\n",
"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.\n",
"responses": {
"200": {
"$ref": "#/components/responses/database"
},
"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.\n\nYou can use the following sort parameter values to sort the results.\n* id (default)\n* username\n",
"parameters": [
{
"$ref": "#/components/parameters/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.\n\n**Please note**, to create a new FTP user, it is required that the corresponding (system) user account is fully set up.\nOtherwise you will receive the **400 Bad Request** error&colon;<br>\n**Invalid property data for&colon; 'uid', 'gid'**\n\nIf the following properties are empty / not set, they are auto-generated&colon;\n* username\n* password\n* home_directory (defaults to /www/)\n\nIf the following properties are auto-generated, they are part of the response&colon;\n* username\n* password\n",
"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.\n",
"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.\n\nSpecify only the fields, you want to update.\n\nIf the following properties are part of the request but empty / null, they are auto-generated&colon;\n* password\n\nIf the following properties are auto-generated, they are part of the response&colon;\n* password\n",
"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.\n",
"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.\n",
"responses": {
"200": {
"$ref": "#/components/responses/ftp-user"
},
"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.\n\nYou can use the following sort parameter values to sort the results.\n* id (default)\n* type\n",
"parameters": [
{
"$ref": "#/components/parameters/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.\n",
"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.\n",
"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.\n\nSpecify only the fields, you want to update. Read the exception below!\n\nATTENTION! When updating the schedule settings, all missing schedule fields in the request will default to `*`.\n\nAs an example, imagine you have a scheduled task with the following settings&colon;<br>\n `minutes = 10`, `hour = 4`, `day_of_week = *`, `month = *`, `day_of_month = 1`\n\nIf 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.\n\nIf you don't do it, and only set the `minutes`, all other values will default to `*`. You would end up with the following&colon;<br>\n `minutes` = 10, `hour = *`, `day_of_week = *`, `month = *`, `day_of_month = *`\n",
"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.\n",
"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.\n\nYou can use the following sort parameter values to sort the results.\n* id (default)\n* auth_name\n* username\n",
"parameters": [
{
"$ref": "#/components/parameters/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.\n\nIf the following properties are empty / not set, they are auto-generated&colon;\n* password\n* path (defaults to /, which corresponds to the user's /www/ directory)\n\nIf the following properties are auto-generated, they are part of the response&colon;\n* password\n",
"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.\n",
"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.\n\nSpecify only the fields, you want to update.\n\nIf the following properties are part of the request but empty / null, they are auto-generated&colon;\n* password\n",
"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.\n",
"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": {
"sort": {
"name": "sort",
"in": "query",
"description": "The property you want to sort by.",
"required": false,
"schema": {
"type": "string"
}
},
"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
}
},
"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"
}
},
"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-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-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-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.\n",
"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"
}
},
"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"
}
},
"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"
}
},
"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-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-task-id": {
"name": "id",
"in": "path",
"description": "Numeric ID of the scheduled task to get.",
"required": true,
"schema": {
"type": "integer",
"minimum": 1
}
},
"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,
"force_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"
}
}
}
},
"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": "string",
"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"
}
}
},
"operating_system": {
"type": "object",
"properties": {
"label": {
"type": "string",
"description": "The OS version in long form.",
"example": "Debian 10.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": 1
}
}
}
}
},
"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
},
"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"
}
}
}
}
}
},
"ping": {
"type": "object",
"properties": {
"response": {
"type": "string",
"example": "pong"
}
}
},
"login-url": {
"description": "The URL to log in to an account.\n",
"type": "object",
"properties": {
"url": {
"type": "string",
"example": "https://keyhelp.example.com/index.php?sso_request=...&sso_token=..."
}
}
},
"admin": {
"description": "Representation of an admin account.\n",
"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.\n",
"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": {
"type": "string",
"writeOnly": true,
"description": "The name of the skeleton directory which should get copied into the users www/ directory.\nThis property is marked as deprecated and should no longer being used.\n",
"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"
}
}
},
"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
}
}
},
"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
}
}
},
"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
}
}
}
}
},
"hosting-plan": {
"description": "Representation of a hosting plan.\n\nThe value \"-1\" for resource properties means \"unlimited\".\n",
"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
},
"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
},
"change_personal_data": {
"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"
},
"additional_settings": {
"type": "string",
"example": "date.timezone = \"US/Central\""
}
}
},
"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.\n",
"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": ""
},
"is_disabled": {
"type": "boolean",
"example": false
},
"delete_on": {
"type": "string",
"format": "date-time",
"example": "2019-08-15T11:29:13+02:00"
},
"dkim_txt_record": {
"type": "string",
"readOnly": true,
"example": "default._domainkey IN TXT ( \"v=DKIM1; k=rsa; s=email; \" \"...DKIM KEY...\" )"
},
"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": false
},
"create_www_subdomain": {
"type": "boolean",
"writeOnly": true,
"default": true,
"description": "Only takes affect when creating a new user.",
"example": true
},
"skeleton": {
"type": "string",
"writeOnly": true,
"description": "The name of the skeleton directory which should get copied into the users www/ directory.\nOnly works if the directory does not already exists.\nThis property is marked as deprecated and should no longer being used.\n",
"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>\nWhen specifing a URL, they have to start with \"http://\" or \"https://.\"\n",
"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>\nYou can only assign certificates with at least \"private_key\" and \"certificate\" component'\n",
"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
},
"force_https": {
"type": "boolean",
"description": "Force automatic forwarding to HTTPS when the domian is accessed via HTTP.",
"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.\n",
"type": "object",
"properties": {
"is_custom_dns": {
"type": "boolean",
"readOnly": true,
"example": false
},
"is_dns_disabled": {
"type": "boolean",
"example": false
},
"dkim_txt_record": {
"type": "string",
"readOnly": true,
"example": "default._domainkey IN TXT ( \"v=DKIM1; k=rsa; s=email; \" \"...DKIM KEY...\" )"
},
"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.\n",
"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"
},
"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.\n",
"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",
"readOnly": true,
"properties": {
"check_virus": {
"type": "boolean",
"example": true
},
"check_spam": {
"type": "boolean",
"example": true
},
"spam_score": {
"type": "number",
"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.\n",
"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": "string",
"format": "array",
"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.\n",
"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.\n",
"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.\n",
"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/"
},
"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#"
]
}
}
}
}