Help us improve your experience.

Let us know what you think.

Do you have time for a two-minute survey?

 

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 - 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.

[ { "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:

  • role - String - The role of the network interface. One of: regular, 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 address that is configured on the network interface. Required when ipversion is ipv4 or (ipversion is ipv6 and is_auto_ip is false). The subnet that is computed from the IP address and the mask must not be the same subnet that is configured on the management interface.

  • mask - String - The netmask that is configured on the network interface. This parameter is required when ipversion is ipv4. The subnet that is computed from the IP address and the mask must not be the same subnet that is configured on the management interface.

  • is_auto_ip - Boolean - Is the IP auto-configured. Required.

  • is_moving_config _with_active_ha - Boolean - Applies the same settings to a new active HA server during failover. This parameter can be true only when the server host is an active HA server host.

{ "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:

  • timezone_id - String - The current time zone.

  • is_sync_with_ntp_server - boolean - Is the NTP service used to synchronize the system time with configured NTP time servers?

  • current__time - Long - The current epoch time (number of milliseconds after Epoch). This parameter must be provided when is_sync_with_ntp_server is false. This parameter must be null if is_sync_with_ntp_server is true.

  • ntp_server_addresses - Array - The array of the NTP server addresses to synchronize the time with. This parameter must be provided when is_sync_with_ntp_server is true. Only the syntax and DNS lookups are checked. The reachability to the ntp servers from the server host are not verified because most ntp servers are rate limited. Four or more NTP servers are recommended for time high accuracy. Must be null if is_sync_with_ntp_server is false.

{ "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" } ]