RUAL Documentation

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.

Key Type Example
:Period string "minute, hour, day, week, month, year"
Key Type Example
authorization string "Bearer 1Z1105da2bac3190b757792066e83f6f3aZ0efa92ae3aebdd6079fa2f328f4dfe2a"
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"
[ { "timestamp": 1738368000, "period": "month", "metric": "disk_usage_mb", "labels": {}, "total": 2785, "count": 2, "date_format": "2025/02/25" } ]
[ { "succes": false, "error": "ERROR_KEY" } ]
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.
-
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.

Key Type Example
:Period string "minute, hour, day, week, month, year"
Key Type Example
authorization string "Bearer 1Z1105da2bac3190b757792066e83f6f3aZ0efa92ae3aebdd6079fa2f328f4dfe2a"
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"
[ { "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 } } ]
[ { "succes": false, "error": "ERROR_KEY" } ]
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.
-
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.

Key Type Example
:type string "zebra printer, dobot"
Key Type Example
authorization string "Bearer 1Z1105da2bac3190b757792066e83f6f3aZ0efa92ae3aebdd6079fa2f328f4dfe2a"
{ "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 } } ] }
{ "success": false, "error": "ERROR_KEY" }
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.
-
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.

{ "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" } }
{ "success": false, "error": "ERROR_KEY" }

This allows for searching and retrieving uploaded media assets (e.g., images, audio files, videos) within the cluster.

{ "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" } } ] }
{ "success": false, "error": "ERROR_KEY" }

This deletes a asset stored in the cluster

Key Type Example
:guid string "8ec9e32063daa34df461fc6954deb4b4606d2b70544fb98464a1416dfc11f0afc01"
{ "guid": "8ec9e32063daa34df461fc6954deb4b4606d2b70544fb98464a1416dfc11f0afc01" }
{ "succes": false, "error": "ERROR_KEY" }
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.
info GET

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.

{ "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 }
{ "success": false, "error": "ERROR_KEY" }
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.

Key Type Example
authorization string "Bearer 1Z1105da2bac3190b757792066e83f6f3aZ0efa92ae3aebdd6079fa2f328f4dfe2a"
{ "developers": "6" }
{ "succes": false, "error": "ERROR_KEY" }
-
permission description
is_root_user this role gives you the highest acces within your cluster