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.

Next Steps

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