Assets — Files in Your Cluster

Store files on your cluster and serve them anywhere: public assets on the /static/ path, private assets behind scopes — uploaded in RUAL Studio or managed through the asset APIs.

What Are Assets?

Assets are files stored centrally on your cluster. Because blueprints are distributed across multiple nodes hosted in various regions, keeping files next to a single node does not work — assets solve this by making every uploaded file available to all your blueprints and all your connected domains, with automatic storage and robust security measures.

There are two kinds of assets:

• Public assets live in the public folder. They are served over HTTP from every connected domain under the /static/ path — no login or token required.
• Private assets live anywhere except the public folder. They are never served directly over HTTP; only your blueprints can read them, so you decide exactly who gets access.

Typical uses are images and fonts for your user interfaces, downloadable files such as exports and invoices, and generated reports you want to keep behind a login.

All public files, regardless of their format, are accessible from all your connected domains using the /static/ path, which maps to the root of the public folder. Referring to the file tree below, the stylesheet is served at /static/styles/mobile.css, while the report in system_assets has no public URL at all.

Uploading Assets in RUAL Studio

The Manage Assets section in RUAL Studio is where you organize folders, upload files, and inspect what is stored on the cluster.

1. Open RUAL Studio and go to Manage Assets. You see the asset folder tree, including the public folder, and the files inside the selected folder.
2. Select the folder you want to upload to — or create a new subfolder first. Remember: anything placed inside public becomes publicly available.
3. Click Upload and pick one or more files from your device.
4. Confirm the upload. The files appear in the file list and are stored on the cluster immediately.
5. Select an uploaded file to open its detail view, where you can review the file metadata and, for public assets, copy the /static/ URL.

Managing Assets with the API

For scripted uploads, integrations, and housekeeping, the cluster ships built-in asset APIs under the System Assets category. All of them require an access_token — see Getting Access — and the token's user needs the matching scope: assets_create to upload and search, assets_remove to delete.

Uploading a File

The upload endpoint takes the file as multipart/form-data and the metadata as query parameters:

curl -X POST "https://<cluster-url>/api/v1/_system/assets/stream?filename=mobile.css&filesize=4821&directory=public&path=styles" \
  -H "Authorization: Bearer <access_token>" \
  -F "file=@mobile.css"

{
  "assets_guid": "9f8e7d6c5b4a3210",
  "name": "mobile.css",
  "type": "text/css"
}

The returned assets_guid identifies the stored asset — keep it when you want to delete the file later. Uploading to directory=public makes the file available at /static/<path>/<filename> right away; system_assets keeps it private.

Searching Assets

The search endpoint accepts a query string with paging, so you can list folders or find a specific file:

{
  "limit": 25,
  "offset": 0,
  "query": "logo"
}

Set "count": true to get the number of matching assets instead of the results. limit defaults to 50 and accepts up to 1000.

Deleting an Asset

curl -X DELETE "https://<cluster-url>/api/v1/_system/assets/9f8e7d6c5b4a3210" \
  -H "Authorization: Bearer <access_token>"

A successful delete returns the removed guid; an unknown guid returns 404. The full request and response schemas live under System Assets APIs.

Public vs Private Assets

The rule of thumb is simple: the public folder decides everything. A file inside it is public no matter what; a file outside it can never be reached by URL guessing, because the /static/ path only maps into public.

Serving Protected Files

To give selected users access to a private asset, serve it through a blueprint and put access control on that blueprint:

1. Create an API or page that loads the file with the get file from assets block and returns it to the caller.
2. Click the lock icon on the block and assign *loggedin — any logged-in user — or a custom scope such as reports, so only users carrying that scope can call it. See Remote Access Control for the full scoping tutorial.
3. Users without the scope are redirected to the forbidden access page (/403).

For downloads straight from the browser — an <a> tag cannot set an Authorization header — pass the token in the URL instead: ?access_token=<token>. Tokens are valid for 14 days and extend automatically while actively used; all five ways to provide a token are documented in Adding tokens to your requests.

Using Assets in Blueprints

The get file from assets block (type file_from_assets, searchable by its alias assets, introduced in v10.4.28) makes files from assets accessible in blueprints. Give it the local path and it hands you a file you can show in the UI or return from an API:

• In-pin — asset path (value, required): the local path to the asset, e.g. /public/images/image.png or a private path outside the public folder.
• Out-pin — success (condition): the asset exists.
• Out-pin — file (file): the file, ready to be used by UI blocks or API responses.
• Out-pins — name, type, size (value, value, number): the filename, the asset type, and the size in bytes.

Public assets can be referenced directly in the UI through their /static/ URL without any block. The block earns its place with private files: it is the only way to pull them into a flow, which is exactly what keeps them protected.

Organizing Folders

A consistent folder layout pays off once assets pile up. Recommended conventions:

• Group by purpose, not by date or uploader: public/styles, public/images, public/downloads for public files, and folders like reports or exports next to — never inside — public for private ones.
• Name for URLs: use lowercase names with hyphens instead of spaces. Folder and file names below public become part of the /static/ URL verbatim.
• Remember the prefix mapping: /static/ points at the root of public, so public/styles/mobile.css is served as /static/styles/mobile.css — the public segment itself never appears in the URL.
• Keep user-generated content out of public unless it is genuinely meant for everyone; move it through a scoped blueprint instead.

File Size, Formats & Performance

• Size limit: the upload API accepts files up to 500MB per file and rejects larger ones with FILE_TOO_BIG. For anything near that limit, prefer the streaming endpoint over base64-style uploads.
• Image formats: serve images as webp — dramatically smaller than PNG or JPEG at the same quality. The function_image_to_webp and function_resize_image blocks convert and resize images in a flow, so you can normalize user uploads before storing them.
• Documents: distribute documents as PDF; it renders consistently on every device and browser.
• Immutable URLs: public assets are ideal CDN and browser-cache candidates because every connected domain serves the same bytes. Give files that change over time a version in the filename — app.v3.css instead of app.css — so clients can cache each version aggressively and you never wait for stale caches to expire. Upload a new name, deploy, and the new URL takes effect immediately.

Next Steps

Was this page helpful? Tell us what to improve · RUAL Docs is an integral component of the RUAL ecosystem