Skip to content

REST API ​

JSON over HTTP at /api/v1. Authenticate with the rk_session cookie (from /auth/login) or Authorization: Bearer rk_… (an API token) or an OIDC access token.

Records ​

MethodPathNotes
GET/metaApps, models (with app, merged overlays and can), dashboards, flows, roles, screens and work (the work screens the caller may open, in order, home marking theirs; contract 0030), connectors, theme tokens (light + dark), layout, site (config, features, redacted system), installed, user, today
GET/r/{model}?filter=<CEL>&sort=-field&limit=50&offset=0&q=text → {data, total}
GET/aggregate/{model}?filter=<CEL>&q=text&group=<field>&fn=count,sum:<field> → {count, values, groups, other?} over the same rows as the list, no paging (below)
POST/r/{model}Create → 201. Defaults and computed fields applied, save rules run
GET · PATCH · DELETE/r/{model}/{name}PATCH merges. Submitted documents return 409
POST/r/{model}/{name}/submit · cancel · amendDocument lifecycle; submit takes {"force": true} to accept warnings; amend → 201. 202 {approval, approvals, record} when the verb waits for approval
POST/r/{model}/{name}/actions/{action}Runs the hook; 202 {job_id} when the action has queue:, 202 as above when it waits for approval
GET/r/{model}/{name}/print?format=<print>&as=html|pdf: the record as a document (Print formats); 501 pdf_unavailable without Chromium
GET/dashboards/{name}?period=30Every widget computed; X-Cache: hit|miss when cached
POST/compute/{model}The record as the model would save it (defaults, computes, child totals), without saving or numbering (contract 0034)
GET/export/r/{model}?filter=&q=&sort=&columns=a,b&sep=semicolon: the list as CSV (UTF-8 with BOM, plain numbers, select labels, Ya/Tidak). Needs the model's export permission on top of read (contract 0024)
GET/export/dashboards/{name}?period=: every widget the caller may export, one CSV block per widget
(header)Idempotency-Key on POST /r/{model}, /submit, /cancel, /amend, /actions/{action}A retry with the same key answers the stored result (Idempotency-Replayed: true) and writes nothing; another body is 409 idempotency_conflict, the same request still running 409 idempotency_in_progress. Body _occurred_at (RFC 3339) goes to the audit (contract 0030 §6, §7)
(body)_if on PATCH /r/{model}/{name}{field: value} checked under the row lock; a mismatch is 409 precondition_failed (contract 0030 §6a)
GET/screens/{name}A work screen the caller may open: {name, screen, set}, set = the screen's set: evaluated for the caller now; 404 otherwise (contract 0030)
POST/flows/{name}/runRun a flow now with {event: {…}}

Attachments ​

Files on records (contract 0011). Not to be confused with /files, which serves the .rk files.

MethodPathNotes
GET/r/{model}/{name}/attachments{data: [{id, filename, content_type, size, sha256, created_by, created_at, url}]}, newest first
POST/r/{model}/{name}/attachmentsMultipart, part file → 201 with the item. 413 too_large over files.max_upload_mb (default 20)
GET/attachments/{id}The bytes; inline for images and PDF, a download otherwise
DELETE/attachments/{id}204. 409 submitted once a submittable record is submitted

files: {enabled: false} in system.rk answers 501 files_disabled.

Approvals ​

Document approvals (contract 0007). A submit, cancel or action that matches an approval policy does not run; it answers 202 and creates a request. When the last pending request is approved, the verb runs as the requester.

MethodPathNotes
GET/approvals?state=pending|approved|rejected|void&model=&name=&limit=50&offset=0 → {data, total}; each item has can_decide
GET/approvals/{id}One request
POST/approvals/{id}/approve · reject{} or {reason}; reject needs a reason. 200 with approval, plus record (or action, flow) when the verb ran. People only

SSE sends event: approval with {id, model, name, state} on every change.

Imports ​

Spreadsheet imports declared in imports/<name>.rk (contract 0012). GET /meta lists them under imports.

MethodPathNotes
POST/imports/{import}Multipart file (CSV or XLSX), form outlet when the import is per outlet. Checks every row in a dry run → {id, import, rows, preview, errors, skipped, duplicate}. 413 too_large over 20 MB
POST/imports/{import}/{id}/commitCreates every record in one transaction. People only. 422 import_errors / import_empty, 409 already_imported
GET/imports/{import} · /imports/{import}/{id}The 50 most recent entries as {data, total}; one entry
GET/imports/{import}/template?format=csv|xlsxA file to fill in: the columns, one example row and (XLSX) a Petunjuk sheet. Default format: the import's source

List aggregates ​

GET /aggregate/{model} answers totals and group summaries for a list view in one request (contract 0018). It matches exactly the rows GET /r/{model} returns for the same q and filter, under the same read grant and row scope, so count always equals the list's total.

  • fn is a comma-separated list of count, sum:<field>, avg:<field>, min:<field> and max:<field> (default count). Values are keyed count and <kind>:<field>.
  • group names a field of the model or a system column such as status or docstatus. The 50 largest groups by count are returned, ties broken by key; the rest are summed into other, which is left out when nothing overflowed. Empty values share one group with key: null, label: "(kosong)". For a link field, label is the linked record's title.
json
{
  "count": 142,
  "values": {"count": 142, "sum:grand_total": 51250000},
  "groups": [
    {"key": "CUST-0012", "label": "CV Maju Jaya", "count": 4, "values": {"count": 4, "sum:grand_total": 3900000}}
  ]
}

Errors: 400 for an unknown or table group, a sum|avg|min|max over a field that is not currency, int, float or percent, a bad fn, a filter that does not compile, or a child model; 404 for an unknown model; 403 without a read grant. There is no preview variant.

Permissions ​

Model permissions: are enforced on every route below, for people, API tokens and MCP alike. Mapping:

RequestAction
GET record, list, /aggregate/{model}, /eventsread
POST /r/{model}create
PATCH, actions/{action}, any other lifecycle verbwrite
DELETEdelete
submit, cancel, amendthe same name
GET /r/{model}/{name}/printprint
GET attachments of a recordread
POST attachments of a record, DELETE /attachments/{id}write
/imports/{import} (upload, commit, read, template)import on its model; each created record also needs create

Child models use their parent's permissions. A flow that a person starts runs as that person, so each step is checked with their roles. A dashboard widget over a model the caller cannot read returns the 403 body in place of its data. Exports need the export permission as well as read.

A refusal is 403:

json
{"error": {"code": "permission_denied", "message": "Kamu tidak punya izin untuk cancel voucher", "model": "voucher", "action": "cancel"}}

A single record the caller may not read answers 403 too, never 404; the print and attachments routes answer action: "read" when the caller cannot read the record. List rows removed by an if: condition are left out and are not counted in total.

GET /meta adds models.<name>.can, an object with a boolean per action (read, create, write, delete, submit, cancel, amend, export, import, print, customize) for the caller. A conditional grant reads as true; the record check still applies. Clients such as the web app and the Console can use it to hide actions the caller may not take.

Errors: 422 {errors:[{field?, rule?, code, message}], warnings?, needs_force?}; everything else {error:{code, message}}. Successful writes may carry _warnings.

Realtime ​

GET /events is a Server-Sent Events stream (?models=deal,lead to filter), with a heartbeat every 15 s:

text
event: record
data: {"model":"deal","name":"DEAL-00012","op":"updated","docstatus":0}

event: changeset
data: {"id":"cs_rzlzncahuf","status":"applied"}

Change sets ​

MethodPathNotes
GET · POST/changesetsList; propose → 201 with layers, risk, status: proposed. An assistant (Raka) proposes over MCP: a change set that touches a part only a person may change (apps/, system.rk, roles, config.ai…) is refused with ai_forbidden_path and the paths (sorted, unique) at structuredContent.detail.paths. Over REST an assistant's write is refused earlier with 403 ai_forbidden
GET/changesets/{id}Full change set with validation, preview (migrations, affected, files[{path, before, after}]) and history. Every change set carries approvable_by: the roles that may approve it (["owner"] for high risk, else config.ai.approvers plus owner, sorted)
POST/changesets/{id}/validate · preview · approve · reject · apply · revertApprove only from previewed, by a signed-in approver; high risk owner only (403 owner_required)

Live preview ​

/preview shows the installation as it would look with a change set applied, read against the live database without migrating it (contract 0015). Only callers who may propose change sets can use it. Responses carry X-Rangka-Preview: <id>.

MethodPathNotes
GET/preview?changeset=<id>{changeset: {id, title, status, risk, layers}, meta}
GET/preview/{id}/meta · /preview/{id}/r/{model} · /preview/{id}/r/{model}/{name} · /preview/{id}/dashboards/{name}Like the live routes

Any other method answers 405 preview_read_only. A change set that changes permissions has no preview (409 preview_permissions).

Process canvas ​

A process is a declared processes/<name>.rk file or one inferred from an app's menu (contract 0014). The graph shows only stages whose model the caller may read.

MethodPathNotes
GET/processes{data: [{name, label, inferred, stages, source}]}, only processes with a stage the caller may read
GET/processes/{name}{name, label, inferred, source, groups, nodes, edges, layout}; 404 not_found for an unknown process or one with no visible stage
POST/processes/{name}/ops{edits: [{node, key, value}]} → {title, ops}; compute only. 400 bad_edit for an unknown or hidden node or key. Send the result to POST /changesets
PUT/processes/{name}/layout{groups: {id: {collapsed?, x?, y?}}, nodes: {id: {x, y}}} → 200 layout, written to site/canvas/<name>.json. Owner only (403 permission_denied); 400 bad_layout for other keys

System and organisation ​

MethodPathNotes
GET/system/statusVersion, uptime, deploy target, schema version, every capability's driver and health, connectors health, OIDC clients
GET/system/jobs?state= · /system/jobs/{id}Queue jobs
POST/system/jobs/{id}/replayQueue a dead-lettered (discarded) job again as a new job → 202 {id, replay_of}. The dead-letter row stays. A connector call is rendered again with the org's current keys, so set the missing key first, then replay. A second replay of the same job returns the first replay. Owner or a connector_auth role only (403; Raka and helpers 403 ai_forbidden); a job that is not dead-lettered → 409 job_not_dead. Audited as job.replay
GET/system/audit?kind=&actor=&org=&limit=Audit log
GET/orgs · /orgs/{id}/membersOrganisations (with plan and usage) and members
GET/files · /files/{path}Every metadata file with kind and layer; one file's text and parsed form (/files/meta/… is an older alias)
POST/tokensCreate an API token: {name, expires_in_days, scopes} → 201, the token shown once; scopes are secrets:write and members:write. Browser sessions only: a token caller gets 403 forbidden
GET/planThe tenant's plan, every plan of features.rk, usage against the limits (ok, near from 80%, full, over), notices and what is read-only after a downgrade (contract 0028)
GET/catalogueEvery module, app and connector this kernel can install, with its state for the site; for people who may propose change sets. Read only for now (contract 0036)

Ruang coba (sandbox org) ​

One sandbox org per site, <org>-coba (code COBA), with demo data. It shares the site's metadata. Connector actions there are simulated (audited as connector.simulated, nothing sent). Webhooks and polls never reach it. Change sets proposed, approved, applied or reverted from it get 409 sandbox_readonly_meta. It is not counted in plan limits or whole-database backups. A cookie rk_org never signs anyone in to it, and it is deleted after 30 days without a request. /auth/me marks it with sandbox: true.

MethodPathNotes
GET/sandboxThe real org's sandbox: {org, created_at, last_used_at, expires_at}, or {} when there is none
POST/sandbox{fixtures: {model: [rows]}} (the rangka seed format) → 201 {org, seeded, generated_skipped}. It creates the sandbox, makes the caller its owner, and seeds the fixtures plus 8 generated rows per company model (x_*). Owner of the real org only (403 owner_required). One per site (409 sandbox_exists)
POST/sandbox/reset{fixtures?}: deletes every row (members and sessions stay) and seeds again, with what create used when fixtures is left out
DELETE/sandboxDeletes the sandbox org and every row of it, append-only ledgers included → 204

From inside the sandbox these routes answer 409 sandbox_inside. CLI: rangka sandbox create|reset|delete --org <id> --fixtures <dir> --email <owner>. See contract 0052.

Connector secrets ​

Write-only (contract 0017): no answer, audit entry, change set, export or log ever holds a secret value, the owner's included. The routes are for the org's owner and roles named in config.rk connector_auth: [role, …]; a sales_rep gets 403 forbidden, Raka and OIDC helpers 403 ai_forbidden. API tokens may read; writing needs a browser session or a token minted with the secrets:write scope (POST /tokens {"name": "cloud", "scopes": ["secrets:write"]}, by a person who may manage secrets; Rangka Cloud provisioning).

MethodPathNotes
GET/connectors/{connector}/auth{connector, org, driver, writable, fields}; per field field, label, secret, required, set, and with the db driver hint (last 4 characters of a value of 16 or more), version, set_by, set_at. Fields that are not secret also return their value
PUT/connectors/{connector}/auth/{field}{"value": "…"} → 204, for the current org. Adds a version; the previous one still verifies inbound webhooks for 24 hours. Audited as secret.set
DELETE/connectors/{connector}/auth/{field}204; removes every version. Audited as secret.delete

system.rk secrets.driver decides where values live. db keeps them in rk_secrets, AES-256-GCM per org with a data key wrapped by RANGKA_MASTER_KEY (rangka keygen); without that key writes answer 409 secrets_key_missing. RANGKA_MASTER_KEY_VAULT=<transit key> keeps that key in Vault transit instead. env, file and vault are read only (409 secrets_read_only_driver): bind fields in system.rkconnector_auth: {<connector>: {<field>: "${VAR}"}}, per org under connector_auth.orgs.<org>. vault reads key VAR of the KV secret at secrets.path (KV v2 secret/data/rangka or v1) with VAULT_ADDR and VAULT_TOKEN. An installed connector shows state: ready in /catalogue once every required field is set.

A change set that installs a connector lists its unset required fields in preview.requires ([{connector, field, label, secret}]). It can still be applied; the connector stays needs_auth until a person sets them.

Members ​

For the host that decides who is a member (Rangka Cloud), keyed by the upstream provider's subject (contract 0043). Only an API token with the members:write scope reaches these routes; a browser session, the owner's included, or a token without the scope gets 403 forbidden. An owner mints it with their own browser session, and it acts in that owner's organisation:

http
POST /api/v1/tokens
{"name": "cloud-members", "expires_in_days": 0, "scopes": ["members:write"]}

A non-owner minting it gets 403 forbidden; a token never mints a token (POST /tokens from any token is 403 forbidden). The token reaches only these two routes: anything else answers 403 scope_limited. Rotate by minting a new token and deleting the old.

MethodPathNotes
PUT/members/{upstream}/{subject}{email, name?, role, outlets?} → 200 {user_id, created}. Creates the person without a password when new, links {subject} of upstream {upstream} (an auth.upstream id), and sets the role and outlets in the token's organisation; omitted outlets keep a member's outlets. A changed e-mail of a linked subject updates the account. A real change of role or outlets revokes the person's sessions and tokens in this organisation. Audited as member.upsert
DELETE/members/{upstream}/{subject}204, also when the subject is unknown or not a member here. Removes the membership in the token's organisation and revokes the person's sessions and tokens there; the account and the link stay. Audited as member.remove

Each call is one transaction and refuses before it writes: 404 unknown_upstream, 409 owner_protected (an owner of any organisation is never created, changed or removed here), 422 unknown_role (also owner), 422 unknown_outlet, 422 bad_request (body or e-mail), 409 identity_conflict (the e-mail's account is linked to another subject at that provider), 409 account_elsewhere (the e-mail's account has a membership in another organisation, or an e-mail change for an account another organisation also holds), 409 email_taken, 403 plan_limit (a new person past the plan's users limit).

Connector webhooks and calls ​

The connector runtime (contract 0002). These routes are not under /api/v1 and need no sign-in: the org's connector secrets verify each request.

MethodPathNotes
POST/hooks/{org}/{connector}/{trigger}A via: webhook trigger. verify.signature is an HMAC over the raw body (sha256= prefix allowed), verify.header + verify.equals a shared token; both are checked against every accepted version of the secret in constant time. Missing or wrong → 401. Body limit 1 MB. Each item of for_each is mapped with emit and starts the installed flows with on: <connector>.<trigger>; the same event again starts nothing
GET/hooks/{org}/{connector}/{trigger}The subscription check of verify.challenge (Meta's hub.verify_token): the right token echoes hub.challenge, a wrong one is 401
POST, GET/hooks/{connector}/{trigger}The same for the site's default org

A flow's call: <connector>.<action> (or a port such as payment.qris.create, mapped by system.rk ports:) queues a call job holding the action, input, org and connector, never the rendered request. The job renders the request in memory, sends it and maps output:; it retries per the action's retry: and is discarded (dead letter) when retries run out or the status is not retried. A request that carries a secret goes only over https to a host in hosts: (else the hosts the connector's own URLs name) and follows redirects only to the same host; anything else fails with secret_host_refused and nothing is sent. Without its keys a call fails with connector_needs_auth, at once. Before audit entries, job errors and stored responses are written, every active secret value of that org and connector (plain, base64, URL-encoded) is replaced with [redacted:<field>]; stored responses are cut to 4 KB. A failed call can be sent again with POST /api/v1/system/jobs/{id}/replay (above).

A via: poll trigger names one of the connector's action:s. Every every: (5m by default, 1m at least) the scheduler queues one poll job per trigger that an installed flow listens to. The slot is aligned to every, so several kernel instances never poll twice. The job sends the action with input:, whose values are CEL over cursor (the stored cursor, null on the first poll) and settings. Its answer (after output:) goes through for_each and emit like a webhook body, with the same dedupe. The next cursor comes from cursor: (CEL over the answer) and is stored per org in rk_poll_cursors. A connector without its keys is skipped ({"skipped": "needs_auth"}), not dead-lettered. A failed poll is not retried: the next slot is the retry.

yaml
triggers:
  - name: new_orders
    via: poll
    every: 5m
    action: list_orders
    input: {since: cursor, limit: "50"}
    cursor: next_cursor
    for_each: orders[]
    emit: {order_id: item.id, phone: item.phone}

each: sends the action once per item, such as per outlet. On every poll the kernel first calls each.action (without input). each.items (CEL over its answer) is the list, and each item is bound under each.as in input: and emit. each.key (CEL over the item) keys the item's own cursor.

yaml
    each: {action: list_outlets, items: outlets, as: outlet, key: outlet.id}
    input: {outlet_id: outlet.id, since: "cursor != null ? cursor : today()"}
    cursor: "size(payments) > 0 ? max(payments.map(p, p.created_at)) : null"

auth.type: basic sends the first secret field as the user name; auth.type: oauth2 refreshes access_token at auth.token_url a minute before expires_at, and a failed refresh removes it so the connector needs auth again.

AI chat ​

The embedded assistant Raka (contract 0020). The kernel relays the chat to the rangka-ai sidecar set with --ai-url, giving it a 10-minute token that acts as the signed-in person over MCP. Raka reads and proposes change sets; it never approves, applies or writes records.

MethodPathNotes
POST/ai/chat{message, history: [{role: user|assistant, text}], context: {route, title, model, record}} → text/event-stream
  • History keeps the last 20 turns and at most 8,000 characters (oldest dropped first). Another role → 400 bad_request.
  • 404 not_found when no sidecar is configured, 403 ai_disabled when config.ai.enabled is false, 403 ai_forbidden for an assistant token.
  • Per person: one chat at a time (429 ai_busy), 30 chats per 10 minutes (429 ai_rate_limited).
  • The stream passes the sidecar's events through: text {delta}, tool {name, summary}, changeset {id, title, risk, status}, escalate {reason}, then done {} or error {code, message}. The kernel itself ends the stream with one error event when the sidecar is down or refuses the request (ai_unavailable, or bad_request when it rejects the body) and after 120 seconds (ai_timeout).
  • GET /meta has features.ai: true when the sidecar answered GET /healthz within the last 30 seconds and config.ai.enabled is not false.
  • Each chat writes one audit entry of kind ai.chat with the tools used, change set ids, duration and outcome; the message text is not stored.
text
event: tool
data: {"name":"rangka_query","summary":"Membaca 20 faktur"}

event: text
data: {"delta":"Ada 20 faktur bulan ini."}

event: done
data: {}

Auth ​

POST /auth/login, POST /auth/logout, GET /auth/me (user with outlets, every org membership, the current org), POST /auth/org {"org": "<id>"} (switch a browser session to another org of the user; tokens have a fixed org: 400 org_fixed; a password session into an org whose auth.password refuses this member's password: 403 password_disabled), and the OIDC endpoints in Rangka ID.

The CRM app's own endpoints, generated from its models with examples, are in the CRM API reference.

Rangka OS is source-available under the Elastic License 2.0 (ELv2). Free to self-host.