Cluster APIs
Below is a comprehensive list of cluster-related APIs that serve various purposes, including asset data, usage statistics, and device data
Retrieve disk usage statistics for the cluster over a given period, including total usage and data count.
URI Params
Key |
Type |
Example |
:Period |
string |
"minute, hour, day, week, month, year" |
Request Headers
Key |
Type |
Example |
authorization |
string |
"Bearer 1Z1105da2bac3190b757792066e83f6f3aZ0efa92ae3aebdd6079fa2f328f4dfe2a" |
Request Body
Key |
Type |
Example |
from: |
string |
"unix timestamp 7 days ago" |
to: |
string |
"current timestamp" |
limit: |
string |
"10" |
metric: |
string |
"disk_usage_mb" |
sort |
string |
"count" |
key_format: |
string |
"YYYY/MM/DD" |
Request Reply: Success
[
{
"timestamp": 1738368000,
"period": "month",
"metric": "disk_usage_mb",
"labels": {},
"total": 2785,
"count": 2,
"date_format": "2025/02/25"
}
]
Request Reply: Error
[
{
"succes": false,
"error": "ERROR_KEY"
}
]
Error Details
Error Code |
Description |
ERROR_KEY |
an error occured while retrieving stats data |
INSUFFICIENT_PERMISSIONS |
aou do not have sufficient permissions to access this resource. |
INVALID_UNIX_TIMESTAMP |
the provided UNIX timestamp is not in a valid format or falls outside the acceptable date range. |
Required permissions
permission |
description |
-
system_cluster_stats |
allows you to retrieve any stats related info off your cluster |
Retrieve cluster statistics over a specified period, including total usage, data count, and average values.
URI Params
Key |
Type |
Example |
:Period |
string |
"minute, hour, day, week, month, year" |
Request Headers
Key |
Type |
Example |
authorization |
string |
"Bearer 1Z1105da2bac3190b757792066e83f6f3aZ0efa92ae3aebdd6079fa2f328f4dfe2a" |
Request Body
Key |
Type |
Example |
from: |
string |
"unix timestamp 7 days ago" |
to: |
string |
"current timestamp" |
limit: |
string |
"10" |
metric: |
string |
"disk_usage_mb" |
sort: |
string |
"count" |
key_format: |
string |
"YYYY/MM/DD" |
Request Reply: Success
[
{
"key_as_string": "2025/02/25",
"key": 1740492000000,
"doc_count": 1,
"total_count": {
"value": 1
},
"total_sum": {
"value": 1393
},
"average_value": {
"value": 1393
}
},
{
"key_as_string": "2025/02/25",
"key": 1740488400000,
"doc_count": 1,
"total_count": {
"value": 1
},
"total_sum": {
"value": 1392
},
"average_value": {
"value": 1392
}
}
]
Request Reply: Error
[
{
"succes": false,
"error": "ERROR_KEY"
}
]
Error Details
Error Code |
Description |
ERROR_KEY |
an error occured while retrieving stats data |
INSUFFICIENT_PERMISSIONS |
you do not have sufficient permissions to access this resource. |
INVALID_UNIX_TIMESTAMP |
the provided UNIX timestamp is not in a valid format or falls outside the acceptable date range. |
Required permissions
permission |
description |
-
system_cluster_stats |
Allows you to retrieve stats related data of your cluster |
Search for local devices on the network and retrieve detailed information including status, ports, and metadata.
URI Params
Key |
Type |
Example |
:type |
string |
"zebra printer, dobot" |
Request Headers
Key |
Type |
Example |
authorization |
string |
"Bearer 1Z1105da2bac3190b757792066e83f6f3aZ0efa92ae3aebdd6079fa2f328f4dfe2a" |
Request Reply: Success
{
"devices": [
{
"type": "device",
"serial": "CR5A03-2780-6386",
"status_port": 22838,
"communication_port": 23055,
"dobot_high_feedback_port": 36362,
"dobot_low_feedback_port": 30486,
"device_type": "dobot",
"model": "CR5A",
"ip_range": "192.168.1.0/24",
"ip": "192.168.1.43",
"status": "ENABLE",
"last_check": 1659976387,
"_meta": {
"guid": "0c93a590b6f84005a4644d49ab4d425e",
"expiry": -1,
"entity": 36,
"removed": 0,
"created": 1723732046,
"updated": 1721974133
}
}
]
}
Request Reply: Error
{
"success": false,
"error": "ERROR_KEY"
}
Error Details
Error Code |
Description |
ERROR_KEY |
an error occurred while searching for local devices |
INSUFFICIENT_PERMISSIONS |
you do not have sufficient permissions to access this resource. |
Required permissions
permission |
description |
-
manage_local_devices |
allows you to manage any local device connect with your cluster |
This requests basic information about the entity such as: hostname, domains, and active status.
Request Reply: Success
{
"active": true,
"entity": "<entity_id>",
"hostname": "example.com",
"domains": [
{
"name": "example.app",
"type": "FORWARD",
"value": "example.com"
},
{
"name": "example.nl",
"type": "FORWARD",
"value": "example.com"
},
{
"name": "app.example.com",
"type": "CNAME"
},
{
"name": "www.example.nl",
"type": "FORWARD",
"value": "example.com"
}
],
"_meta": {
"guid": "example-guid",
"expiry": -1,
"entity": 0,
"removed": 0,
"created": 1636880692,
"updated": 1716484936,
"ums": 1716484936184,
"cms": 1636880692374,
"update_hash": "example-hash"
}
}
Request Reply: Error
{
"success": false,
"error": "ERROR_KEY"
}
This allows for searching and retrieving uploaded media assets (e.g., images, audio files, videos) within the cluster.
Request Reply: Success
{
"assets": [
{
"version": 1,
"directory": "/public",
"hash": "98c6733a04e995f9b5b22b920bb47f97de13fdf453d2a77a82e9298e6540c29a",
"name": "background-image.png",
"type": "image/png",
"path": "/public/background-image.png",
"_meta": {
"guid": "9c1f29caf24441ccbf8315b5787aec42",
"expiry": -1,
"entity": 7849,
"removed": 0,
"created": 1678981963,
"updated": 1678981963,
"ums": 1678981963798,
"cms": 1678981963798,
"update_hash": "74a368efb2e08032875bb792b728d054852c867a339a0bc1486518109fc38d79"
}
},
{
"version": 1,
"directory": "/public/fonts/SF/",
"hash": "98c6733a04e995f9b5b22b920bb47f97de13fdf453d2a77a82e9298e6540c29a",
"name": "SF-Pro-Display-LightItalic.woff",
"type": "application/font-woff",
"path": "/public/fonts/SF/SF-Pro-Display-LightItalic.woff",
"_meta": {
"guid": "161f10e6b71848ac908f6bf56aa416e0",
"expiry": -1,
"entity": 7849,
"removed": 0,
"created": 1679083100,
"updated": 1679083100,
"ums": 1679083100362,
"cms": 1679083100362,
"update_hash": "e7852f6024fad52ad85923423298fe4fe71e36d06ea51e2af1a03bd5c742c3b2"
}
}
]
}
Request Reply: Error
{
"success": false,
"error": "ERROR_KEY"
}
This deletes a asset stored in the cluster
URI Params
Key |
Type |
Example |
:guid |
string |
"8ec9e32063daa34df461fc6954deb4b4606d2b70544fb98464a1416dfc11f0afc01" |
Request Reply: Success
{
"guid": "8ec9e32063daa34df461fc6954deb4b4606d2b70544fb98464a1416dfc11f0afc01"
}
Request Reply: Error
{
"succes": false,
"error": "ERROR_KEY"
}
Error Details
Error Code |
Description |
ERROR_KEY |
an error occured while deleting asset. |
NO_GUID_IN_PARAMS |
this indicates that the GUID is missing or not correctly provided in the request. |
COULD_NOT_FIND_FTLF |
given asset could not be found, or does not exist. |
Retrieve detailed server and environment information. This endpoint returns the cluster hostname, the current cluster worker id (or 'M' for master), RUAL core version with metrics status, the active entity, feature flags, and the production status. This endpoint is public.
Request Reply: Success
{
"host": "deverence-39-n01",
"thread": 2,
"core": {
"version": "v13.0.9",
"metrics": true
},
"entity": 39,
"flags": {
"has_remote_auth": true,
"has_uicomponents": false
},
"production": true
}
Request Reply: Error
{
"success": false,
"error": "ERROR_KEY"
}
Error Details
Error Code |
Description |
ERROR_KEY |
an error occurred while retrieving server information. |
this request basic data usage information about the entity such as; quantity developers and file usage.
Request Headers
Key |
Type |
Example |
authorization |
string |
"Bearer 1Z1105da2bac3190b757792066e83f6f3aZ0efa92ae3aebdd6079fa2f328f4dfe2a" |
Request Reply: Success
{
"developers": "6"
}
Request Reply: Error
{
"succes": false,
"error": "ERROR_KEY"
}
Required permissions
permission |
description |
-
is_root_user |
this role gives you the highest acces within your cluster |