system

10 endpoints
GET/rest/nodeHealth/status

Get node health status for system monitoring

Description:

Retrieves node health status information for system components including MariaDB cluster status, required services status, memory usage, and system load average.

Precondition:

This endpoint is restricted by IP whitelist and rate limiting.

Response:

Returns the overall node health status.
This endpoint requires no parameters.
Responses

Node health status returned successfully - all components are healthy.

ok
integer

Overall health status indicator. 1 means all components are healthy; 0 means one or more components are unhealthy.

Request blocked by WAF

Empty response body.

ERR_INTERNAL_SERVER_ERROR

Empty response body.

Service unavailable - one or more components are unhealthy.

ok
integer

Overall health status indicator. 1 means all components are healthy; 0 means one or more components are unhealthy.

Shell
curl -X GET \
  "https://{instance}.kiteworks.com/rest/nodeHealth/status" \
  -H "Authorization: Bearer YOUR_TOKEN"
Python
import requests

url = "https://{instance}.kiteworks.com/rest/nodeHealth/status"
headers = {
    "Authorization": "Bearer YOUR_TOKEN",
}
response = requests.get(url, headers=headers)
print(response.json())
Responses
{ "ok": 1 }
// Error - No Body
// Error - No Body
{ "ok": 0 }
POST/rest/system/epgdb/import/{id}

Upload EPGDB backup chunk for database restore

Endpoint for uploading a chunk to an existing EPGDB backup upload session, identified by its session ID.

Parameters
Path Parameters
id
Required
string

The upload session ID

Request Body
filename
Required
string

The filename of the EPGDB backup file being uploaded.

Responses

Successfully received the upload

id
string

Upload session ID

Unauthorized

Possible error codes: ERR_AUTH_INVALID_CSRF, ERR_AUTH_UNAUTHORIZED

code
string

Error code

message
string

Error message

Forbidden

Possible error codes: ERR_ACCESS_DENIED, ERR_ACCESS_USER

code
string

Error code

message
string

Error message

Unprocessable Content

Possible error codes: ERR_INVALID_PARAMETER, ERR_FILE_TOO_LARGE

code
string

Error code

message
string

Error message

Request blocked by WAF

Empty response body.

Service Unavailable

Possible error codes: ERR_SESSION_LIMIT_REACHED, ERR_UPLOAD_CHUNK_FAILED

code
string

Error code

message
string

Error message

Insufficient Storage

Possible error codes: ERR_INSUFFICIENT_DISK_SPACE

code
string

Error code

message
string

Error message

Shell
curl -X POST \
  "https://{instance}.kiteworks.com/rest/system/epgdb/import/:id" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
         "filename": "string"
       }'
Python
import requests

id = "VALUE"  # The upload session ID

url = f"https://{{instance}}.kiteworks.com/rest/system/epgdb/import/{id}"
headers = {
    "Authorization": "Bearer YOUR_TOKEN",
    "Content-Type": "application/json",
}
payload = {
  "filename": "string"
}
response = requests.post(url, headers=headers, json=payload)
print(response.json())
Responses
{ "id": "string" }
{ "errors": [ { "code": "ERR_AUTH_INVALID_CSRF", "message": "Invalid CSRF Authentication" } ] }
{ "errors": [ { "code": "ERR_AUTH_UNAUTHORIZED", "message": "Unauthorized" } ] }
{ "errors": [ { "code": "ERR_ACCESS_DENIED", "message": "Your access is denied.", "redirectUrl": "/login?code=3317" } ] }
{ "errors": [ { "code": "ERR_ACCESS_USER", "message": "Insufficient access permissions" } ] }
{ "errors": [ { "code": "ERR_INVALID_PARAMETER", "message": "Invalid Parameter Exception" } ] }
{ "errors": [ { "code": "ERR_FILE_TOO_LARGE", "message": "Size of the file exceeds the allowed limit." } ] }
// Error - No Body
{ "errors": [ { "code": "ERR_SESSION_LIMIT_REACHED", "message": "Session limit reached. Unable to create a new session." } ] }
{ "errors": [ { "code": "ERR_UPLOAD_CHUNK_FAILED", "message": "Upload chunk failed." } ] }
{ "errors": [ { "code": "ERR_INSUFFICIENT_DISK_SPACE", "message": "Server does not have enough storage to process the upload." } ] }
GET/rest/system/epgdb/import

Get EPGDB import status

Endpoint for polling the status of the import

This endpoint requires no parameters.
Responses

Successfully returned the import status

Empty response body.

Unauthorized

Possible error codes: ERR_AUTH_INVALID_CSRF, ERR_AUTH_UNAUTHORIZED

code
string

Error code

message
string

Error message

Forbidden

Possible error codes: ERR_ACCESS_DENIED, ERR_ACCESS_USER

code
string

Error code

message
string

Error message

Unprocessable Content

Possible error codes: ERR_INVALID_PARAMETER

code
string

Error code

message
string

Error message

Request blocked by WAF

Empty response body.
Shell
curl -X GET \
  "https://{instance}.kiteworks.com/rest/system/epgdb/import" \
  -H "Authorization: Bearer YOUR_TOKEN"
Python
import requests

url = "https://{instance}.kiteworks.com/rest/system/epgdb/import"
headers = {
    "Authorization": "Bearer YOUR_TOKEN",
}
response = requests.get(url, headers=headers)
print(response.json())
Responses
// Request successful - No Body
{ "errors": [ { "code": "ERR_AUTH_INVALID_CSRF", "message": "Invalid CSRF Authentication" } ] }
{ "errors": [ { "code": "ERR_AUTH_UNAUTHORIZED", "message": "Unauthorized" } ] }
{ "errors": [ { "code": "ERR_ACCESS_DENIED", "message": "Your access is denied.", "redirectUrl": "/login?code=3317" } ] }
{ "errors": [ { "code": "ERR_ACCESS_USER", "message": "Insufficient access permissions" } ] }
{ "errors": [ { "code": "ERR_INVALID_PARAMETER", "message": "Invalid Parameter Exception" } ] }
// Error - No Body
POST/rest/system/epgdb/import

Upload EPGDB backup for database restore

Endpoint for uploading an EPGDB backup for restoring the database. Starts a new upload session.

Request Body
filename
Required
string

The filename of the EPGDB backup file being uploaded.

Responses

Successfully received the upload

id
string

Upload session ID

Unauthorized

Possible error codes: ERR_AUTH_INVALID_CSRF, ERR_AUTH_UNAUTHORIZED

code
string

Error code

message
string

Error message

Forbidden

Possible error codes: ERR_ACCESS_DENIED, ERR_ACCESS_USER

code
string

Error code

message
string

Error message

Unprocessable Content

Possible error codes: ERR_INVALID_PARAMETER, ERR_FILE_TOO_LARGE

code
string

Error code

message
string

Error message

Request blocked by WAF

Empty response body.

Service Unavailable

Possible error codes: ERR_SESSION_LIMIT_REACHED, ERR_UPLOAD_CHUNK_FAILED

code
string

Error code

message
string

Error message

Insufficient Storage

Possible error codes: ERR_INSUFFICIENT_DISK_SPACE

code
string

Error code

message
string

Error message

Shell
curl -X POST \
  "https://{instance}.kiteworks.com/rest/system/epgdb/import" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
         "filename": "string"
       }'
Python
import requests

url = "https://{instance}.kiteworks.com/rest/system/epgdb/import"
headers = {
    "Authorization": "Bearer YOUR_TOKEN",
    "Content-Type": "application/json",
}
payload = {
  "filename": "string"
}
response = requests.post(url, headers=headers, json=payload)
print(response.json())
Responses
{ "id": "string" }
{ "errors": [ { "code": "ERR_AUTH_INVALID_CSRF", "message": "Invalid CSRF Authentication" } ] }
{ "errors": [ { "code": "ERR_AUTH_UNAUTHORIZED", "message": "Unauthorized" } ] }
{ "errors": [ { "code": "ERR_ACCESS_DENIED", "message": "Your access is denied.", "redirectUrl": "/login?code=3317" } ] }
{ "errors": [ { "code": "ERR_ACCESS_USER", "message": "Insufficient access permissions" } ] }
{ "errors": [ { "code": "ERR_INVALID_PARAMETER", "message": "Invalid Parameter Exception" } ] }
{ "errors": [ { "code": "ERR_FILE_TOO_LARGE", "message": "Size of the file exceeds the allowed limit." } ] }
// Error - No Body
{ "errors": [ { "code": "ERR_SESSION_LIMIT_REACHED", "message": "Session limit reached. Unable to create a new session." } ] }
{ "errors": [ { "code": "ERR_UPLOAD_CHUNK_FAILED", "message": "Upload chunk failed." } ] }
{ "errors": [ { "code": "ERR_INSUFFICIENT_DISK_SPACE", "message": "Server does not have enough storage to process the upload." } ] }
DELETE/rest/system/epgdb/import

Cancel active EPGDB import session

Endpoint for cancelling the current active import session

This endpoint requires no parameters.
Responses

Successfully deleted the session

Empty response body.

Unauthorized

Possible error codes: ERR_AUTH_INVALID_CSRF, ERR_AUTH_UNAUTHORIZED

code
string

Error code

message
string

Error message

Forbidden

Possible error codes: ERR_ACCESS_DENIED, ERR_ACCESS_USER

code
string

Error code

message
string

Error message

Request blocked by WAF

Empty response body.
Shell
curl -X DELETE \
  "https://{instance}.kiteworks.com/rest/system/epgdb/import" \
  -H "Authorization: Bearer YOUR_TOKEN"
Python
import requests

url = "https://{instance}.kiteworks.com/rest/system/epgdb/import"
headers = {
    "Authorization": "Bearer YOUR_TOKEN",
}
response = requests.delete(url, headers=headers)
print(response.json())
Responses
// Request successful - No Body
{ "errors": [ { "code": "ERR_AUTH_INVALID_CSRF", "message": "Invalid CSRF Authentication" } ] }
{ "errors": [ { "code": "ERR_AUTH_UNAUTHORIZED", "message": "Unauthorized" } ] }
{ "errors": [ { "code": "ERR_ACCESS_DENIED", "message": "Your access is denied.", "redirectUrl": "/login?code=3317" } ] }
{ "errors": [ { "code": "ERR_ACCESS_USER", "message": "Insufficient access permissions" } ] }
// Error - No Body
GET/rest/system/epgdb/export/{filename}

Download EPGDB export file

Get EPGDB export download

Parameters
Path Parameters
filename
Required
string

The name of the EPGDB export file to download.

Responses

EPGDB export download

Empty response body.

Unauthorized

Possible error codes: ERR_AUTH_INVALID_CSRF, ERR_AUTH_UNAUTHORIZED

code
string

Error code

message
string

Error message

Forbidden

Possible error codes: ERR_ACCESS_DENIED, ERR_ACCESS_USER, ERR_DB_BACKUP_FAILED

code
string

Error code

message
string

Error message

Request blocked by WAF

Empty response body.
Shell
curl -X GET \
  "https://{instance}.kiteworks.com/rest/system/epgdb/export/:filename" \
  -H "Authorization: Bearer YOUR_TOKEN"
Python
import requests

filename = "VALUE"  # The name of the EPGDB export file to download.

url = f"https://{{instance}}.kiteworks.com/rest/system/epgdb/export/{filename}"
headers = {
    "Authorization": "Bearer YOUR_TOKEN",
}
response = requests.get(url, headers=headers)
print(response.json())
Responses
// Request successful - No Body
{ "errors": [ { "code": "ERR_AUTH_INVALID_CSRF", "message": "Invalid CSRF Authentication" } ] }
{ "errors": [ { "code": "ERR_AUTH_UNAUTHORIZED", "message": "Unauthorized" } ] }
{ "errors": [ { "code": "ERR_ACCESS_DENIED", "message": "Your access is denied.", "redirectUrl": "/login?code=3317" } ] }
{ "errors": [ { "code": "ERR_ACCESS_USER", "message": "Insufficient access permissions" } ] }
{ "errors": [ { "code": "ERR_DB_BACKUP_FAILED", "message": "Database backup failed due to an unexpected error" } ] }
// Error - No Body
GET/rest/system/epgdb/export

Get EPGDB export status

Get EPGDB export status

This endpoint requires no parameters.
Responses

EPGDB export status returned successfully

Empty response body.

Unauthorized

Possible error codes: ERR_AUTH_INVALID_CSRF, ERR_AUTH_UNAUTHORIZED

code
string

Error code

message
string

Error message

Forbidden

Possible error codes: ERR_ACCESS_DENIED, ERR_ACCESS_USER

code
string

Error code

message
string

Error message

Request blocked by WAF

Empty response body.
Shell
curl -X GET \
  "https://{instance}.kiteworks.com/rest/system/epgdb/export" \
  -H "Authorization: Bearer YOUR_TOKEN"
Python
import requests

url = "https://{instance}.kiteworks.com/rest/system/epgdb/export"
headers = {
    "Authorization": "Bearer YOUR_TOKEN",
}
response = requests.get(url, headers=headers)
print(response.json())
Responses
// Request successful - No Body
{ "errors": [ { "code": "ERR_AUTH_INVALID_CSRF", "message": "Invalid CSRF Authentication" } ] }
{ "errors": [ { "code": "ERR_AUTH_UNAUTHORIZED", "message": "Unauthorized" } ] }
{ "errors": [ { "code": "ERR_ACCESS_DENIED", "message": "Your access is denied.", "redirectUrl": "/login?code=3317" } ] }
{ "errors": [ { "code": "ERR_ACCESS_USER", "message": "Insufficient access permissions" } ] }
// Error - No Body
POST/rest/system/epgdb/export

Start EPGDB export

Start EPGDB export with precheck validation

This endpoint requires no parameters.
Responses

EPGDB export started successfully

Empty response body.

Unauthorized

Possible error codes: ERR_AUTH_INVALID_CSRF, ERR_AUTH_UNAUTHORIZED

code
string

Error code

message
string

Error message

Forbidden

Possible error codes: ERR_ACCESS_DENIED, ERR_ACCESS_USER, ERR_JOB_IN_PROGRESS

code
string

Error code

message
string

Error message

Not Found

Possible error codes: ERR_EPGDB_NOT_FOUND

code
string

Error code

message
string

Error message

Request blocked by WAF

Empty response body.

Insufficient Storage

Possible error codes: ERR_INSUFFICIENT_TMP_STORAGE

code
string

Error code

message
string

Error message

Shell
curl -X POST \
  "https://{instance}.kiteworks.com/rest/system/epgdb/export" \
  -H "Authorization: Bearer YOUR_TOKEN"
Python
import requests

url = "https://{instance}.kiteworks.com/rest/system/epgdb/export"
headers = {
    "Authorization": "Bearer YOUR_TOKEN",
}
response = requests.post(url, headers=headers)
print(response.json())
Responses
// Request successful - No Body
{ "errors": [ { "code": "ERR_AUTH_INVALID_CSRF", "message": "Invalid CSRF Authentication" } ] }
{ "errors": [ { "code": "ERR_AUTH_UNAUTHORIZED", "message": "Unauthorized" } ] }
{ "errors": [ { "code": "ERR_ACCESS_DENIED", "message": "Your access is denied.", "redirectUrl": "/login?code=3317" } ] }
{ "errors": [ { "code": "ERR_ACCESS_USER", "message": "Insufficient access permissions" } ] }
{ "errors": [ { "code": "ERR_JOB_IN_PROGRESS", "message": "The job is currently still in progress" } ] }
{ "errors": [ { "code": "ERR_EPGDB_NOT_FOUND", "message": "Failed to locate EPGDB" } ] }
// Error - No Body
{ "errors": [ { "code": "ERR_INSUFFICIENT_TMP_STORAGE", "message": "Insufficient storage space in the Tmp storage partition" } ] }
DELETE/rest/system/epgdb/export

Perform cleanup for EPGDB export

Perform cleanup for EPGDB export

This endpoint requires no parameters.
Responses

Delete EPGDB export

Empty response body.

Unauthorized

Possible error codes: ERR_AUTH_INVALID_CSRF, ERR_AUTH_UNAUTHORIZED

code
string

Error code

message
string

Error message

Forbidden

Possible error codes: ERR_ACCESS_DENIED, ERR_ACCESS_USER, ERR_JOB_IN_PROGRESS

code
string

Error code

message
string

Error message

Request blocked by WAF

Empty response body.
Shell
curl -X DELETE \
  "https://{instance}.kiteworks.com/rest/system/epgdb/export" \
  -H "Authorization: Bearer YOUR_TOKEN"
Python
import requests

url = "https://{instance}.kiteworks.com/rest/system/epgdb/export"
headers = {
    "Authorization": "Bearer YOUR_TOKEN",
}
response = requests.delete(url, headers=headers)
print(response.json())
Responses
// Request successful - No Body
{ "errors": [ { "code": "ERR_AUTH_INVALID_CSRF", "message": "Invalid CSRF Authentication" } ] }
{ "errors": [ { "code": "ERR_AUTH_UNAUTHORIZED", "message": "Unauthorized" } ] }
{ "errors": [ { "code": "ERR_ACCESS_DENIED", "message": "Your access is denied.", "redirectUrl": "/login?code=3317" } ] }
{ "errors": [ { "code": "ERR_ACCESS_USER", "message": "Insufficient access permissions" } ] }
{ "errors": [ { "code": "ERR_JOB_IN_PROGRESS", "message": "The job is currently still in progress" } ] }
// Error - No Body
GET/rest/nodeHealth/{node_id}/metrics/{metric_name}

Get node health metrics for specified metric type

Description:

Retrieves health metrics for database, web requests, job queue, SFTP, system resources, or all metrics.

Precondition:

The user must be an administrator with access to `System Services`.

Response:

Returns the list of metrics for the specified metric type.
Parameters
Path Parameters
node_id
Required
string

Kiteworks node id to retrieve metrics from.

metric_name
Required
string

The type of metric to retrieve.

Responses

The node health metrics have been successfully returned.

service_status
string

The MariaDB service status.
active – Service is running.
inactive – Service is not running.

active_connection_count
integer

Real-time number of active database connections.

wsrep_cluster_status
string

Galera cluster status indicating whether this node is the primary component.

wsrep_cluster_size
integer

Number of healthy nodes in the Galera cluster.

wsrep_local_state_comment
string

Galera local state indicating readiness to accept read/write requests. Synced is the healthy value.

memory_usage_mb
integer

Real-time RSS memory usage of the MariaDB service in MB.

cpu_usage_percentage
number

Real-time CPU usage percentage by the MariaDB service.

db_partition_free_mb
integer

Free space available on the database partition in MB.

db_partition_used_mb
integer

Used space on the database partition in MB.

status
string

The Nginx service status.
active – Service is running.
inactive – Service is not running.

active_connections
integer

Real-time number of active connections to the local Nginx instance.

reading
integer

Real-time number of connections currently reading the request header.

writing
integer

Real-time number of connections currently writing a response.

connection_efficiency
number

Ratio of handled connections to accepted connections.

avg_requests_per_connection
number

Ratio of total requests to handled connections.

service_status
string

The job queue service status.
active – Service is running.
inactive – Service is not running.

memory_usage_mb
integer

RSS memory usage of the job queue service in MB.

queue_jq_acfs_conv
integer

Number of jobs in the file preview queue.

queue_jq_scan
integer

Number of jobs in the antivirus scan queue.

queue_jq_acfs
integer

Number of fingerprint jobs queued to be executed on the ACFS node.

current_queued_job_count
integer

Real-time number of jobs currently waiting in the queue.

current_working_job_count
integer

Real-time number of jobs currently being processed.

current_failed_job_count
integer

Real-time number of jobs that have failed.

active_connection_count
integer

Number of active SFTP connections.

memory_usage_mb
integer

Total RSS memory usage by SFTP processes in MB.

total_memory_usage_mb
integer

Total system RSS memory usage in MB.

total_swap_usage_mb
integer

Total system swap usage in MB.

total_cpu_usage_percent
number

Total system CPU usage as a percentage.

system_load_average_1min
number

System load average over the last 1 minute.

system_load_average_5min
number

System load average over the last 5 minutes.

system_load_average_15min
number

System load average over the last 15 minutes.

Unauthorized

Possible error codes: ERR_ACCESS_USER, ERR_AUTH_INVALID_CSRF, ERR_AUTH_UNAUTHORIZED

code
string

Error code

message
string

Error message

Unprocessable Content

Possible error codes: ERR_INVALID_PARAMETER

code
string

Error code

message
string

Error message

Request blocked by WAF

Empty response body.

Internal Server Error

Possible error codes: ERR_INTERNAL_SERVER_ERROR

code
string

Error code

message
string

Error message

Shell
curl -X GET \
  "https://{instance}.kiteworks.com/rest/nodeHealth/:node_id/metrics/:metric_name" \
  -H "Authorization: Bearer YOUR_TOKEN"
Python
import requests

node_id = "VALUE"  # Kiteworks node id to retrieve metrics from.
metric_name = "VALUE"  # The type of metric to retrieve.

url = f"https://{{instance}}.kiteworks.com/rest/nodeHealth/{node_id}/metrics/{metric_name}"
headers = {
    "Authorization": "Bearer YOUR_TOKEN",
}
response = requests.get(url, headers=headers)
print(response.json())
Responses
{ "kw_database": {}, "web_requests": {}, "jobqueued": {}, "sftp": {}, "system_resources": {} }
{ "errors": [ { "code": "ERR_ACCESS_USER", "message": "Insufficient access permissions" } ] }
{ "errors": [ { "code": "ERR_AUTH_INVALID_CSRF", "message": "Invalid CSRF Authentication" } ] }
{ "errors": [ { "code": "ERR_AUTH_UNAUTHORIZED", "message": "Unauthorized" } ] }
{ "errors": [ { "code": "ERR_INVALID_PARAMETER", "message": "Invalid Parameter Exception" } ] }
// Error - No Body
{ "errors": [ { "code": "ERR_INTERNAL_SERVER_ERROR", "message": "Internal Server Error" } ] }
Previoussources
Nextuploads