API Guide: Working with RUAL APIs

Public vs private APIs, token authentication, request and response conventions, error codes, rate limits, and the workflows you will use daily, with curl examples.

Every RUAL cluster exposes REST APIs under /api/v1: the built-in Cluster APIs (blueprints, users, storages, system operations) plus any custom API you build with an API blueprint. This guide covers how to call them correctly; the API reference lists every endpoint with its parameters and example responses.

Public vs Private APIs

You set the audience per API block with its lock icon: *public, *loggedin (any valid token), or a custom scope you invent (e.g. billing_read) and then grant to selected users. See Remote Access Control.

Authentication

API calls authenticate with an access_token, obtained through the sign-in APIs (or via RUAL Studio). Tokens are valid for 14 days and automatically extend while actively used. You do not need to re-login during normal operation.

The token is accepted in five equivalent locations, pick one:

What a token may do is decided by the user's scopes and the token's custom_scopes. See User Roles & Permissions Explained. On clusters with two-factor authentication enforced, sign-in additionally requires the current 2FA code.

Request Conventions

• Base URL, https://<your-cluster>/api/v1. All endpoints live under it.
• Content type: send and receive application/json unless an endpoint documents otherwise (file upload uses multipart/form-data).
• Search endpoints: accept Elasticsearch-style queries: term (exact match), terms (one of many), match (full-text), range (dates/numbers), plus limit and offset for pagination.
• Documents. Every stored object carries a _meta object with guid, created, updated, and removal state.

Error Responses

Errors return a JSON object with the HTTP status, a machine-readable code and a message:

{
  "error": "DOCUMENT_NOT_FOUND",
  "message": "The requested document does not exist."
}

Rate Limiting

Public APIs default to 100 requests per second per endpoint. Custom APIs have their own configurable rate limit and throttle (lock & wait) fields: documented per block in Remote Access Control. When you receive a 429, retry with exponential backoff and jitter; do not retry in a tight loop.

Common API Workflows

1. Sign in to get a token

curl -X POST "https://your-cluster.rual.dev/api/v1/auth/signin" \
  -H "Content-Type: application/json" \
  -d '{"username": "you@example.com", "password": "..."}'

The response contains your access_token: reuse it for subsequent calls.

2. Search documents in a storage

curl -X POST "https://your-cluster.rual.dev/api/v1/_system/storages/search" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer eyJhbGciOi..." \
  -d '{"limit": 10}'

3. Call a custom blueprint API

curl "https://your-cluster.rual.dev/api/v1/tasks?access_token=eyJhbGciOi..."

Your own endpoints registered with an on api get block behave like any other API on the cluster: same auth, same error shapes. See Build Your First API.

Quick Reference

The full list with per-endpoint parameters, example responses, and required scopes lives in the Cluster API reference.

apig endpoints

Next Steps

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