System Endpoints
Use the references for REST API V8.0 system endpoints.
GET /system/information/locales
Retrieves a list of locales from the system, with the option to include samples.
Table 1: GET /system/information/locales Resource Details
MIME Type |
---|
application/json |
Table 2: GET /system/information/locales Request Parameter Details
Parameter | Type | Optionality | Data Type | MIME Type | Description |
---|---|---|---|---|---|
sample_type | query | Optional | String | text/plain | Optional - type of samples for the locale. Currently the only supported option is NUMBER. |
Range | header | Optional | String | text/plain | Optional - Use this parameter to restrict the number of elements that are returned in the list to a specified range. The list is indexed starting at zero. |
filter | query | Optional | String | text/plain | Optional - This parameter is used to restrict the elements in a list base on the contents of various fields. |
fields | query | Optional | String | text/plain | Optional - Use this parameter to specify which fields you would like to get back in the response. Fields that are not named are excluded. Specify subfields in brackets and multiple fields in the same object are separated by commas. |
Table 3: GET /system/information/locales Response Codes
HTTP Response Code | Unique Code | Description |
---|---|---|
200 | The requested list of locales was retrieved. | |
500 | 1020 | An error occurred during the attempt to retrieve the list of locales. |
Response Description
A list of locales. A locale contains the following fields:
id - String - The tag of the locale.
label - String - The name of the locale.
sample - String - The optional sample for the locale.
Response Sample
[ { "id": "sq", "label": "Albanian", "sample":
"1 234 567,89" }, { "id": "sq-AL", "label": "Albanian
(Albania)", "sample": "1 234 567,89" }, { "id": "ar",
"label": "Arabic", "sample": "١٬٢٣٤٬٥٦٧٫Ù̈Ù©"
}, { "id": "ar-DZ", "label": "Arabic (Algeria)", "sample":
"1.234.567,89" }, { "id": "ar-BH", "label": "Arabic (Bahrain)",
"sample": "١٬٢٣٤٬٥٦٧٫Ù̈Ù©"
} ]
GET /system/servers
Retrieve a list of all server hosts in the deployment.
Table 4: GET /system/servers Resource Details
MIME Type |
---|
application/json |
Table 5: GET /system/servers Request Parameter Details
Parameter | Type | Optionality | Data Type | MIME Type | Description |
---|---|---|---|---|---|
filter | query | Optional | String | text/plain | Optional - This parameter is used to restrict the elements in a list base on the contents of various fields. |
Range | header | Optional | String | text/plain | Optional - Use this parameter to restrict the number of elements that are returned in the list to a specified range. The list is indexed starting at zero. |
fields | query | Optional | String | text/plain | Optional - Use this parameter to specify which fields you would like to get back in the response. Fields that are not named are excluded. Specify subfields in brackets and multiple fields in the same object are separated by commas. |
Table 6: GET /system/servers Response Codes
HTTP Response Code | Unique Code | Description |
---|---|---|
200 | The requested list of server records has been successfully retrieved. | |
500 | 1020 | An error has occurred while trying to retrieve the requested servers. |
Response Description
A list of the servers. A server record contains the following fields:
hostname - String - hostname
managed_host_id - Number - Id of the managed host the server host belongs to
private_ip - String - The private ip of this server
status - String - The status of this server
Response Sample
[ { "hostname": "String", "managed_host_id":
42, "private_ip": "String", "server_id": 42,
"status": "String" } ]
GET /system/servers/{server_id}
Retrieve a server host based on the supplied server ID.
Table 7: GET /system/servers/{server_id} Resource Details
MIME Type |
---|
application/json |
Table 8: GET /system/servers/{server_id} Request Parameter Details
Parameter | Type | Optionality | Data Type | MIME Type | Description |
---|---|---|---|---|---|
server_id | path | Required | Number (Integer) | text/plain | Required - The id of the server |
fields | query | Optional | String | text/plain | Optional - Use this parameter to specify which fields you would like to get back in the response. Fields that are not named are excluded. Specify subfields in brackets and multiple fields in the same object are separated by commas. |
Table 9: GET /system/servers/{server_id} Response Codes
HTTP Response Code | Unique Code | Description |
---|---|---|
200 | The requested server record has been retrieved. | |
404 | 1002 | The requested server record with the given server_id cannot be found. |
422 | 1005 | One or more parameters are invalid in request. |
500 | 1020 | An error has occurred while trying to retrieve the requested server host with the given Id. |
Response Description
A server record containing the following fields:
email_server_address - String - email server address
hostname - String - hostname
managed_host_id - Number - Id of the managed host the server host belongs to
private_ip - String - The private ip of this server
status - String - The status of this server
Response Sample
{ "email_server_address": "String", "hostname": "String",
"managed_host_id": 42, "private_ip": "String", "server_id":
42, "status": "String" }
POST /system/servers/{server_id}
Updates an existing server.
Table 10: POST /system/servers/{server_id} Resource Details
MIME Type |
---|
application/json |
Table 11: POST /system/servers/{server_id} Request Parameter Details
Parameter | Type | Optionality | Data Type | MIME Type | Description |
---|---|---|---|---|---|
server_id | path | Required | Number (Integer) | text/plain | Required - The id of the server. |
Table 12: POST /system/servers/{server_id} Request Body Details
Parameter | Data Type | MIME Type | Description | Sample |
---|---|---|---|---|
details | Object | application/json | Required - A server details record containing the following field: email_server_address - String - email server address. Must be a valid server address that the server can connect to through port 25. | { "email_server_address": "String" } |
Table 13: POST /system/servers/{server_id} Response Codes
HTTP Response Code | Unique Code | Description |
---|---|---|
200 | The server record has been updated. | |
404 | 1002 | The requested server record with the given server_id cannot be found. |
422 | 1005 | One or more parameters are invalid in request. |
422 | 1006 | Cannot connect to the mail server address on port 25. |
500 | 1020 | An error has occurred while trying to retrieve the requested server host with the given Id. |
Response Description
The updated server record containing the following fields:
email_server_address - String - email server address.
hostname - String - hostname
managed_host_id - Number - Id of the managed host the server host belongs to
private_ip - String - The private ip of this server
status - String - The status of this server
Response Sample
{ "email_server_address": "String", "hostname": "String",
"managed_host_id": 42, "private_ip": "String", "server_id":
42, "status": "String" }
GET /system/servers/{server_id}/firewall_rules
Retrieve a list of access control firewall rules based on the supplied server ID.
Table 14: GET /system/servers/{server_id}/firewall_rules Resource Details
MIME Type |
---|
application/json |
Table 15: GET /system/servers/{server_id}/firewall_rules Request Parameter Details
Parameter | Type | Optionality | Data Type | MIME Type | Description |
---|---|---|---|---|---|
server_id | path | Required | Number (Integer) | text/plain | Required - The id of the server. |
filter | query | Optional | String | text/plain | Optional - This parameter is used to restrict the elements in a list base on the contents of various fields. |
Range | header | Optional | String | text/plain | Optional - Use this parameter to restrict the number of elements that are returned in the list to a specified range. The list is indexed starting at zero. |
fields | query | Optional | String | text/plain | Optional - Use this parameter to specify which fields you would like to get back in the response. Fields that are not named are excluded. Specify subfields in brackets and multiple fields in the same object are separated by commas. |
Table 16: GET /system/servers/{server_id}/firewall_rules Response Codes
HTTP Response Code | Unique Code | Description |
---|---|---|
200 | The rules records have been retrieved. | |
404 | 1002 | The requested server with the given server_id cannot be found. |
422 | 1005 | One or more parameters are invalid in request. |
500 | 1020 | An error has occurred while trying to retrieve the requested access control firewall rules on the server with the given Id. |
Response Description
A list of the rules. Each rule record contains the following fields:
is_any_source_ip - Boolean - Whether any source IP is accepted
port_range - String - A port range in the format of start-end
port_type - String - one of: ANY, SINGLE, RANGE
protocol - String - one of: ANY, TCP, UDP
single_port - String - A single port
source_ip - String - A specific IP address
Response Sample
[ { "is_any_source_ip": true, "port_range":
"String", "port_type": "String <one of: ANY, SINGLE, RANGE>",
"protocol": "String <one of: ANY, TCP, UDP>", "single_port":
"String", "source_ip": "String" } ]
PUT /system/servers/{server_id}/firewall_rules
Set the access control firewall rules based on the supplied server ID.
Table 17: PUT /system/servers/{server_id}/firewall_rules Resource Details
MIME Type |
---|
application/json |
Table 18: PUT /system/servers/{server_id}/firewall_rules Request Parameter Details
Parameter | Type | Optionality | Data Type | MIME Type | Description |
---|---|---|---|---|---|
server_id | path | Required | Number (Integer) | text/plain | Required - The id of the server. |
Table 19: PUT /system/servers/{server_id}/firewall_rules Request Body Details
Parameter | Data Type | MIME Type | Description | Sample |
---|---|---|---|---|
rules | Array<Object> | application/json | Required - A list of new rules in a JSON string. Each rule record contains the following field:
| [ { "is_any_source_ip": true, "port_range": "String", "port_type": "String <one of: ANY, SINGLE, RANGE>", "protocol": "String <one of: ANY, TCP, UDP>", "single_port": "String", "source_ip": "String" } ] |
Table 20: PUT /system/servers/{server_id}/firewall_rules Response Codes
HTTP Response Code | Unique Code | Description |
---|---|---|
200 | The rules have been updated. | |
404 | 1002 | The requested server with the given server_id cannot be found. |
422 | 1005 | One or more parameters are invalid in request. |
500 | 1020 | An error has occurred while trying to set the access control firewall rules on the server with the given Id. |
Response Description
A list of the rules in a JSON string. Each rule contains the following fields:
is_any_source_ip - Boolean - Whether any source IP is accepted
port_range - String - A port range in the format of start-end
port_type - String - one of: ANY, SINGLE, RANGE
protocol - String - one of: ANY, TCP, UDP
single_port - String - A single port
source_ip - String - A specific IP address
Response Sample
[ { "is_any_source_ip": true, "port_range":
"String", "port_type": "String <one of: ANY, SINGLE, RANGE>",
"protocol": "String <one of: ANY, TCP, UDP>", "single_port":
"String", "source_ip": "String" } ]
GET /system/servers/{server_id}/network_interfaces/ethernet
Retrieves a list of the ethernet network interfaces based on the supplied server ID.
Table 21: GET /system/servers/{server_id}/network_interfaces/ethernet Resource Details
MIME Type |
---|
application/json |
Table 22: GET /system/servers/{server_id}/network_interfaces/ethernet Request Parameter Details
Parameter | Type | Optionality | Data Type | MIME Type | Description |
---|---|---|---|---|---|
server_id | path | Required | Number (Integer) | text/plain | Required - The id of the server. |
fields | query | Optional | String | text/plain | Optional - Use this parameter to specify which fields you would like to get back in the response. Fields that are not named are excluded. Specify subfields in brackets and multiple fields in the same object are separated by commas. |
filter | query | Optional | String | text/plain | Optional - This parameter is used to restrict the elements in a list base on the contents of various fields. |
Range | header | Optional | String | text/plain | Optional - Use this parameter to restrict the number of elements that are returned in the list to a specified range. The list is indexed starting at zero. |
Table 23: GET /system/servers/{server_id}/network_interfaces/ethernet Response Codes
HTTP Response Code | Unique Code | Description |
---|---|---|
200 | A list of the ethernet network interfaces were retrieved. | |
404 | 1002 | The requested server with the given server ID cannot be found. |
422 | 1005 | One or more parameters are invalid in request. |
500 | 1020 | An error occurred while trying to retrieve the ethernet interfaces on the server with the given ID. |
500 | 1022 | Timeout while performing the task. |
Response Description
A list of the ethernet network interfaces. Each ethernet network interface contains the following fields:
device_name - String - The name of the network interface.
desc - String - The description of the network interface.
role - String - The role of the network interface. One of: regular, management, hacrossover, hacrossover_disabled, monitor, disabled.
ipversion - String - The verson of the IP address that is configured on the network interface. One of: ipv4, ipv6.
ip - String - The IP that is configured on the network interface.
mask - String - The netmask that is configured on the network interface
is_auto_ip - Boolean - Is the IP auto-configured?
is_cable_linked - String - Is the network interface cable linked? One of: true, false, unknown.
is_moving_config_with_active_ha - Boolean -Applies the same settings to a new active HA server during failover.
hacrossover_params - String - A map of key-value pairs of HA crossover parameters if the network interface is used for HA crossover.
Response Sample
[ { "desc": "String", "device_name":
"String", "hacrossover_params": { "String": "String"
}, "ip": "String", "ipversion": "String <one
of: ipv4, ipv6>", "is_auto_ip":
true, "is_cable_linked": "String <one of: true,
false,
unknown>", "is_moving_config_with_active_ha":
true, "mask": "String", "role": "String <one of:
regular, management,
hacrossover,
hacrossover_disabled, monitor,
disabled,
slave, slave_disabled>"
} ]
POST /system/servers/{server_id}/network_interfaces/ethernet/{device_name}
Updates an ethernet network interface based on the suppied server_Id and device_name.
Table 24: POST /system/servers/{server_id}/network_interfaces/ethernet/{device_name} Resource Details
MIME Type |
---|
application/json |
Table 25: POST /system/servers/{server_id}/network_interfaces/ethernet/{device_name} Request Parameter Details
Parameter | Type | Optionality | Data Type | MIME Type | Description |
---|---|---|---|---|---|
server_id | path | Required | Number (Integer) | text/plain | Required - The ID of the server. |
device_name | path | Required | String | text/plain | Required - The name of an existing ethernet network interface. The interface cannot be the management interface, HA crossover interface or a slave of a bonded interface. The interface must be cable linked. |
Table 26: POST /system/servers/{server_id}/network_interfaces/ethernet/{device_name} Request Body Details
Parameter | Data Type | MIME Type | Description | Sample |
---|---|---|---|---|
details | Object | application/json | Required - An ethernet network interface record containing the following fields:
| { "ip": "String", "ipversion": "String <one of: ipv4, ipv6>", "is_auto_ip": true, "is_moving_config_with_active_ha": true, "mask": "String", "role": "String <one of: regular, management, hacrossover, hacrossover_disabled, monitor, disabled, slave, slave_disabled>" } |
Table 27: POST /system/servers/{server_id}/network_interfaces/ethernet/{device_name} Response Codes
HTTP Response Code | Unique Code | Description |
---|---|---|
200 | The network interface has been updated. | |
404 | 1002 | The requested server with the given server ID cannot be found. |
409 | 1004 | The ip address has been used by another network interface. |
422 | 1005 | One or more parameters are invalid in request. |
500 | 1020 | An error occurred while trying to update the specified ethernet interfaces on the server with the given ID. |
500 | 1022 | Timeout while performing the task. |
Response Description
The updated ethernet network interface containing the following fields:
device_name - String - The name of the network interface.
role - String - The role of the network interface. One of: regular, management, hacrossover, hacrossover_disabled, monitor, disabled.
ipversion - String - The verson of the that is IP address that is configured on the network interface. One of: ipv4, ipv6.
ip - String - The IP address that is configured on the network interface.
mask - String - The netmask configured on the network interface.
is_auto_ip - Boolean - Is the IP address auto-configured.
is_moving_config_with_active_ha - Boolean - Applies the same settings to a new active HA server during failover.
Response Sample
{ "desc": "String", "device_name": "String",
"hacrossover_params": { "String": "String" }, "ip":
"String", "ipversion": "String <one of: ipv4,
ipv6>", "is_auto_ip": true, "is_cable_linked":
"String <one of: true,
false, unknown>", "is_moving_config_with_active_ha":
true, "mask": "String", "role": "String <one of: regular,
management,
hacrossover, hacrossover_disabled,
monitor,
disabled, slave,
slave_disabled>" }
GET /system/servers/{server_id}/system_time_settings
Retrieves the system time and time zone settings of a server host based on the supplied server ID.
Table 28: GET /system/servers/{server_id}/system_time_settings Resource Details
MIME Type |
---|
application/json |
Table 29: GET /system/servers/{server_id}/system_time_settings Request Parameter Details
Parameter | Type | Optionality | Data Type | MIME Type | Description |
---|---|---|---|---|---|
server_id | path | Required | Number (Integer) | text/plain | Required - The ID of the server. |
fields | query | Optional | String | text/plain | Optional - Use this parameter to specify which fields you would like to get back in the response. Fields that are not named are excluded. Specify subfields in brackets and multiple fields in the same object are separated by commas. |
Table 30: GET /system/servers/{server_id}/system_time_settings Response Codes
HTTP Response Code | Unique Code | Description |
---|---|---|
200 | The requested system time settings record was retrieved. | |
404 | 1002 | The requested system time settings record with the given server ID cannot be found. |
422 | 1005 | One or more parameters are invalid in the request. |
500 | 1020 | An error occurred during the attempt to retrieve the requested system time settings with the given server ID. |
500 | 1022 | Timeout while performing the task. |
Response Description
Server system time settings that contain the following fields:
timezone_id - String - the current time zone
current_time - Long - The current epoch time (number of milliseconds after Epoch).
is_sync_with_ntp_server - Boolean - Whether the NTP service is used to synchronize the system time with configured NTP time servers.
ntp_server_addresses - Array - The array of the configured NTP server addresses. Null if is_sync_with_ntp_server is false.
Response Sample
{ "current_time": 42, "ntp_server_addresses": [
"String" ], "sync_with_ntp_server": true, "timezone_id":
"String" }
POST /system/servers/{server_id}/system_time_settings
Sets the system time and time zone settings of a server host. Services are restarted after the call and service interruptions will occur.
Table 31: POST /system/servers/{server_id}/system_time_settings Resource Details
MIME Type |
---|
application/json |
Table 32: POST /system/servers/{server_id}/system_time_settings Request Parameter Details
Parameter | Type | Optionality | Data Type | MIME Type | Description |
---|---|---|---|---|---|
server_id | path | Required | Number (Integer) | text/plain | Required - The ID of the server |
fields | header | Optional | String | text/plain | Optional - Use this parameter to specify which fields you would like to get back in the response. Fields that are not named are excluded. Specify subfields in brackets and multiple fields in the same object are separated by commas. |
Table 33: POST /system/servers/{server_id}/system_time_settings Request Body Details
Parameter | Data Type | MIME Type | Description | Sample |
---|---|---|---|---|
settings | Object | application/json | Server system time settings that contain the following fields:
| { "current_time": 42, "ntp_server_addresses": [ "String" ], "sync_with_ntp_server": true, "timezone_id": "String" } |
Table 34: POST /system/servers/{server_id}/system_time_settings Response Codes
HTTP Response Code | Unique Code | Description |
---|---|---|
200 | The system time settings have been applied. | |
404 | 1002 | The requested server with the given server ID cannot be found. |
422 | 1005 | One or more parameters are invalid in request. |
500 | 1020 | An error occurred during the attempt to apply the system time settings to the server. |
500 | 1022 | Timeout during performance of the task. |
Response Description
Server system time settings that contain the following fields:
timezone_id - String - The current time zone.
current_time - Long - The current epoch time (number of milliseconds after Epoch).
is_sync_with_ntp_server - Boolean - Whether the NTP service is used to synchronize the system time with configured NTP time servers.
ntp_server_addresses - Array - The array of the configured NTP server addresses. Null if is_sync_with_ntp_server is false.
Response Sample
{ "current_time": 42, "ntp_server_addresses": [
"String" ], "sync_with_ntp_server": true, "timezone_id":
"String" }
GET /system/servers/{server_id}/timezones
Retrieves all the available time zones that can be set for a server.
Table 35: GET /system/servers/{server_id}/timezones Resource Details
MIME Type |
---|
application/json |
Table 36: GET /system/servers/{server_id}/timezones Request Parameter Details
Parameter | Type | Optionality | Data Type | MIME Type | Description |
---|---|---|---|---|---|
server_id | path | Required | Number (Integer) | text/plain | Required - The ID of the server |
fields | query | Optional | String | text/plain | Optional - Use this parameter to specify which fields you would like to get back in the response. Fields that are not named are excluded. Specify subfields in brackets and multiple fields in the same object are separated by commas. |
Table 37: GET /system/servers/{server_id}/timezones Response Codes
HTTP Response Code | Unique Code | Description |
---|---|---|
200 | The requested timezone records were retrieved. | |
404 | 1002 | The requested timezone records with the given server ID cannot be found. |
422 | 1005 | One or more parameters are invalid in the request. |
500 | 1020 | An error occurred during the attempt to retrieve the requested timezone records with the given server Id. |
500 | 1022 | Timeout during the performance of the task. |
Response Description
A list of time zones that contains the following fields:
id - String - the ID of time zone.
timezone - String - The formatted string representation of the timezone in the current locale.
offset - Integer - Number of milliseconds offset to UTC time at the moment.
Response Sample
[ { "id": "String", "offset": 42,
"timezone": "String" } ]