Skip to content
All technical docs Bricks technical documentation

The RPC API & workflows

How to run server-side logic on Bricks — the two RPC surfaces, how workflows are built and triggered, the full catalogue of available nodes, and the expression rules that trip everyone up once.

The RPC API & workflows

Bricks Technical Documentation

How to run server-side logic on Bricks — the two RPC surfaces, how workflows are built and triggered, the full catalogue of available nodes, and the expression rules that trip everyone up once.


When you need Bricks to do something on the server — validate a payment callback, send an invitation, transform an upload, expose a custom endpoint — you build a workflow. A workflow is a graph of nodes that runs governed logic and returns a shaped HTTP response. This page covers how to call server logic, how workflows execute and trigger, every node you can use, and the one expression mistake that silently breaks conditions.

Two ways to call server logic

Bricks does not ship a separate "RPC framework." There are two real surfaces:

  • Database functions over the data API. Any function exposed in a tenant's schema is callable at POST /rest/v1/rpc/{function}, selected with the same Accept-Profile/Content-Profile headers as table access. These appear in the tenant's OpenAPI spec (see schema discovery).
  • Workflow webhooks — the way to publish a custom endpoint. To expose a callable tenant function of your own, build a workflow that starts with a webhook trigger and ends with a response node, then call it at:
POST | GET  /v2/workflows/webhook/{tenantSchema}/{webhookPath}

The response is whatever the workflow's terminal output node returns. This is the true "tenant function" mechanism — it runs governed node logic rather than raw SQL, and returns a shaped HTTP response.

Authoring & maintaining workflows

Workflows are authored and maintained through Studio AI, not hand-edited. In the product the only editing affordance on a workflow is "Edit with AI": you describe the change and the assistant rewrites the workflow's { nodes, connections }. This is deliberate — the assistant writes the workflow and records it in the tenant's concept graph in the same step, so the semantic graph and its ontologies stay consistent with what the workflow actually does. Every write is validated; the node catalogue the assistant builds from is public at /v2/workflow-node-catalog.

Everyday API use is read, run, and inspect:

Method Path Purpose
GET /v2/workflows/:id Read a workflow
POST /v2/workflows/execute Manual run by id (as: "schedule" runs it with the payload a scheduled tick sends)
ALL /v2/workflows/webhook/:schema/:path Public webhook trigger
GET /v2/workflows/:id/executions Execution history
GET /v2/workflows/:id/openapi Per-workflow OpenAPI spec
GET /v2/workflow-node-catalog Available node types

There are lower-level create/update/delete endpoints (POST /v2/tenants/:id/workflows, PUT / PATCH / DELETE /v2/workflows/:id, org-admin-gated), but they are a programmatic administrative surface, not the authoring path. Mutating a workflow's definition directly bypasses the concept-graph stewardship the assistant performs, so the semantic graph can drift out of sync with the workflow. Use them only from integrations that take on that responsibility — otherwise build and maintain workflows through Studio AI.

How a workflow executes

Execution is a breadth-first walk of the node graph. Nodes with no incoming connection are the start set. Each node runs, its output becomes the next node's input, and results are also addressable by node name (so a later node can read $node['Validate'].user). Branching nodes select which downstream connections to follow; failures route down error connections and every failed node carries a human-readable message. A runaway loop is capped hard.

mermaid diagram

Triggers — the principle

A trigger is the first node, whose type name starts with trigger-. A workflow starts in one of these ways:

  • HTTP webhook (trigger-webhook) — an external POST/GET to the workflow's public webhook URL. It requires a webhook_path slug. File uploads arrive as attachments on the trigger.
  • Manual (trigger-manual) — run from the Studio, or via the management API with trigger data.
  • Schedule (trigger-schedule) — run by the platform clock, on the cadence of a schedule (cron expression, timezone, tolerance) attached to the workflow. The workflow receives scheduled_for, schedule_id and lag_seconds. Each occurrence runs at most once: a run interrupted mid-way is marked for a human, never replayed, because its earlier steps may already have sent mail or created a payment. If a scheduled workflow keeps failing, it is marked in red in the workflow list and on its page, and the Bricks team is notified (immediately, then at a widening interval); nothing is switched off. To stop a scheduled workflow for a while, pause its schedule with the Pause button on the workflow's page (Resume restarts it from its next occurrence). Switching the workflow itself off, or writing "disabled" in its name, does not stop the schedule. The page also shows how many runs each schedule had over the last 30, 15 and 7 days and today, and, for any workflow, who triggered its recent unhandled failures (a failed step no error branch took over) and when, for as long as your organisation keeps run details. The error text itself is not shown, because it can contain the data the run carried.
  • Invitation accepted (trigger-invitation-accepted) — fires once when someone accepts an invitation to your organisation, after their role is granted. Accepting an invitation writes nothing in your own tables, so this is how a new member becomes a row in your model. It receives user_id, email, full_name, role_name, role_names, language and the invitation details. A failure never undoes the acceptance and is not retried, so make it idempotent.
  • Integration webhooks (trigger-mollie-webhook, trigger-leexi-webhook) — fired automatically when a connected vendor calls back, branching on the vendor's status.
  • ActivityPub inbox (trigger-activitypub-inbox) — fired when an activity reaches your organisation's space on the Fediverse (a follow, a reply, a like, a post from a space you follow), after Bricks has verified who sent it. It tells you which BricksID followed only when that person agreed to it by following. Your workflow decides what to accept and where to store what came in. See Bricks as a social network.
  • Another workflow — through the action-run-workflow node (see below).

Every trigger except the HTTP webhook is matched to its workflow by id: it must not declare a webhook_path.

Expressions — read this once

Node fields read the running context through expressions. Two languages exist; the prefix decides which one evaluates a field.

ELO — the language for new expressions. A field value that starts with elo: is an ELO expression. It reads one input, _: _.json.<field> (the trigger input), _.node.<nodeId>.<field> (a prior node's output), _.vars.<name> (a variable you set). It has and, or, not, parentheses, if … then … else, functions (first, count, sortBy, filter, contains, min, max, sum, …), and real dates and durations. A malformed ELO expression is refused when the workflow is saved, and an expression that cannot be evaluated fails the step with an error.

elo: first(_.node.lookup).id
elo: if count(_.node.lookup) > 0 then first(_.node.lookup).id else null
elo: contains(_.node.authenticate.user.role_names, 'org_admin')

When a lookup can find nothing, fall back to null, never to a placeholder like 'none' or '': a null filter simply matches no row, while a placeholder is rejected by a uuid, number or date column. Studio AI refuses such placeholders when saving a workflow, and the step fails with a message naming the field and the column type if one reaches it at run time.

Legacy {{ … }} templates — still run in existing workflows. Path roots are $json, $node.Name.path and $vars.name, plus four read-only namespaces about the run itself: $tenant (.id, .schema, .slug, .name), $workflow (.id, .name, .environment, .execution_id), $integration.<key>.config.<setting> (your non-secret integration settings) and $platform.frontend_url. Inside the braces you can use comparisons, || (first-truthy fallback), + - * /, a ternary and literals — but no &&, !, parentheses or functions. Studio AI writes new expressions in ELO and keeps legacy ones editable where they already exist.

The one legacy mistake. An operator placed outside the braces is a silent always-true bug. Written like this:

{{$json.status}} === 'paid'

the template resolves to the status string and leaves === 'paid' as literal text — a non-empty string, which is truthy, so a condition node always takes the true branch. Studio AI refuses to save this shape. In ELO the whole comparison is one expression:

elo: _.json.status == 'paid'

Credentials are never readable from an expression. Nodes that call a vendor attach your stored credential themselves; never put a key or a token in a header, a body or a URL.

Governed egress and role assignment

Two behaviors are worth calling out because they are enforced, not advisory:

  • Outbound HTTP is governed. The nodes that call an external URL funnel through a single gate that blocks private/internal targets and requires a signed data-flow declaration for the destination host before the request is allowed. An undeclared host fails by design — that is the correct outcome, not a bug. See Data flows.
  • Workflows can only assign non-system roles. The role-assignment node cannot grant or revoke org_admin or platform_admin; that restriction lives in the database, so it holds even against a hand-edited workflow. The invitation node refuses them too. Administrative roles stay in the Admin UI.
mermaid diagram

Reusing a workflow, and serving a file

  • Calling another workflow. action-run-workflow runs another workflow of your organisation as one step and returns its output, so a validation or a notification is written once and called from many places. The called workflow must be marked callable by its author; it receives your input unwrapped (it reads _.node.trigger.<field>). The result carries a definition hash of exactly what ran — pass it back as expectedDefinition to refuse the call if that workflow has changed since. Nesting is limited to 5 levels, a workflow cannot call itself through a chain, and the whole chain shares one execution budget.
  • Serving a calendar feed or a CSV. output-respond can answer with contentType text/calendar, text/csv or text/plain instead of JSON (with an optional download filename). Combined with data-ics-build, a webhook becomes a subscribable calendar: trigger-webhook (GET, with a token) → action-verify-sha-api-key → action-db-query → data-ics-build → output-respond (text/calendar). text/html is not allowed.

Execution history

Every run is one entry in the workflow's execution history (GET /v2/workflows/:id/executions): status, timings, the error, and the per-step trace. Credentials the caller sent (Authorization, cookies, API keys, bearer tokens) are replaced by [redacted] before anything is stored; the history records who called instead — a user id, or the id of the API key, when the workflow's own authentication step proved it. Fields your organisation marked "never keep" in its retention charter are withheld. The per-step trace is cleared after your organisation's trace retention window (90 days unless you set another); the entry itself, with its status and error, stays.

When a step fails, the error says which step, of which type, failed and why — for example the field and the column type a value could not be stored in, never the value itself.

The node catalogue

Every node you can place in a workflow, grouped by purpose:

Category Nodes
Triggers trigger-webhook, trigger-manual, trigger-schedule, trigger-invitation-accepted, trigger-mollie-webhook, trigger-leexi-webhook, trigger-activitypub-inbox
Logic & flow logic-if (condition → true/false branch), logic-contains (array/string membership → branch), action-run-workflow (call another callable workflow)
Output output-respond (HTTP body/status; JSON, calendar, CSV or plain text), output-redirect (302), output-set-variable (store a variable)
Tenant data action-db-query (parameterized CRUD — preferred — and totals computed by the database: count, sum, average, min, max, optionally per group and within a date or amount range), action-rest-api (whole table or one row by id)
Authentication & users action-authenticate (verify a bearer token), action-authenticate-api-key, action-generate-sha-api-key / action-verify-sha-api-key (mint/verify share tokens), action-lookup-tenant-user, action-get-user-profile, action-assign-tenant-role (non-system only), action-invite-tenant-user (non-system only), action-add-dependent (ask to add someone the person acts for; they confirm on BricksID), action-request-signature (ask the authenticated person to sign a PDF on BricksID), action-read-signature (read the outcome and its sealed proof)
Integrations action-http-request (governed outbound REST), action-dataspace-request (Dataspace-Protocol consumer), action-mollie-create-payment / action-mollie-get-payment, action-mollie-create-pay-link (a payment link that still works when opened later), action-mollie-create-plan / -get-plan / -stop-plan (a subscription or instalment plan Mollie debits automatically), action-create-payment-notification, action-leexi-get-call / -list-calls, action-run-harness (call a declared AI harness), action-activitypub-deliver (publish to your space's followers, inside Bricks and on the Fediverse; a post addressed to roles never leaves Bricks), action-activitypub-fetch (read a post or profile from another server)
Storage & documents action-s3-upload / -download / -list / -delete / -move / -copy, action-pdf-fill (fill a PDF form), action-media-set-audience (change who may see files in the media library)
Calendar & reminders action-create-event-notification (with ICS + auto reminders), action-amend-event-notification, action-schedule-reminder, action-send-notification (notify a person in BricksID, with push where they turned it on)
Email action-email (via the org's email integration)
Data transforms data-filter (keep the rows matching one predicate), data-render-template (substitute {{var}}), data-string-split / data-string-join, data-ics-build / data-ics-parse (rows ↔ iCalendar), data-activitypub-build / data-activitypub-parse (rows ↔ ActivityPub posts), action-file-read-table (CSV/TSV/XLSX → rows), data-iterate-start / data-iterate-end (loop over an array), action-now (server time), action-generate-uuid, action-tokenize / action-detokenize (store a value encrypted with the organisation's own key, still comparable in queries, and read it back), action-split-dates, action-media-resolve (media id → file), action-lint-text (check text against rules)

Gotchas worth keeping in view

  1. Write new expressions in ELO (elo: prefix). In a legacy {{ }} template, an operator outside the braces is a silent always-true.
  2. Fall back to null, not to a placeholder — 'none' or '' in a uuid, number or date column fails the step.
  3. webhook_path is required for a webhook trigger and forbidden for every other trigger.
  4. The response node returns what you build — each body field keeps its type, so choose the fields the caller needs rather than returning whole rows.
  5. Egress needs a signed data flow first — an undeclared host fails by design.
  6. Workflows can never assign administrative roles — enforced in the database.
  7. A scheduled run is never replayed automatically — make scheduled workflows safe to run again by hand.

This page describes shipped behavior. Workflows are most often authored through Studio AI tools; their outbound calls are governed by Data flows; the data they read and write is protected by the data API's permission model.