Build a feature with the API
Most people build a Feature by asking Ronja in a chat. You can also build one over HTTP with a scoped API token: scriptable, repeatable, and with no AI spend. This guide creates a Feature, adds a Workflow and an App, then shares the Feature.
This is the tutorial; the contract is the API reference on your Ronja address. Start from <your-org>.ronja.tech/llms.txt, which links every endpoint with the scope it needs; see API reference.
Before you start: mint a token
Section titled “Before you start: mint a token”- Follow Create an API token. Name it (e.g.
feature builder) and pick a Role that bounds what it can do. - Keep Limited to scopes and grant only what your script needs:
- Structure → Write to create the Feature;
- Automation → Write to create and publish the Workflow;
- Analytics → Write to create and commit the App;
- Data → Write to create and fill tables;
- Secrets → Write or Agents → Write only if the Feature uses secrets or Saved Agents.
- Copy the secret from the Token created modal. It is shown only once.
Send it on every request as a Bearer token:
export RONJA_BASE_URL="https://<your-org>.ronja.tech"export RONJA_API_TOKEN="<paste your token>"alias rapi='curl -sS -H "Authorization: Bearer $RONJA_API_TOKEN"'A script can’t mint tokens: every token, including a narrower one for a sub-task, is created by an Admin in the web UI (Actions the API can’t take). For the self-approval policy, a token counts as the Admin who created it, so have a different Admin, or that feature’s maintainer, decide that person’s work. While self-approval is off, deleting a token strands what it filed; see Tokens and self-approval.
The recipe
Section titled “The recipe”1. Create the Feature
Section titled “1. Create the Feature”scope is private (the default) or organization to share it, which needs Admin. Only you and your organization’s Admins can find a private Feature; see Scopes.
rapi -X POST "$RONJA_BASE_URL/api/v2/feature" \ -d '{"name":"Weekly sales report","scope":"private"}'# -> 200 {"id":"<feature-id>","name":"Weekly sales report", ...}Save the returned Feature id: everything below is created inside it.
2. Get data in (optional)
Section titled “2. Get data in (optional)”A Workflow that reads a table needs the table first. Send data via the API covers creating, filling and building one; come back with your table ids (table-...).
3. Create and publish the Workflow
Section titled “3. Create and publish the Workflow”A Workflow is created as a draft, given its code, then published.
# Create the draft — featureID is required.rapi -X POST "$RONJA_BASE_URL/api/v2/workflow" \ -d '{"featureID":"<feature-id>","title":"Roll up weekly sales","runtimeVersion":4}'# -> 200 {"id":"workflow_...", "lifecycle":"draft", ...}
# Push the code. Markers in the body attach the workflow's data dependencies.# The body is a heredoc so the SQL keeps its own quotes.rapi -X PUT "$RONJA_BASE_URL/api/v2/workflow/workflow_.../files/main.py" \ --data-binary @- <<'JSON'{"content":"def main():\n weekly = tools.query(\"SELECT week, SUM(amount) AS amount FROM {{ ref('table-8f21c4') }} GROUP BY week\")\n tools.replaceTable(weekly, {{ write('weekly_sales') }})\n return {\"weeks\": len(weekly)}\n"}JSON
# Publish the draft to make it live.rapi -X POST "$RONJA_BASE_URL/api/v2/workflow/workflow_.../publish"With "runtimeVersion": 4, Ronja calls the main your main.py defines, passing the Workflow’s parameters as named arguments, and what it returns is the run’s result. Leave runtimeVersion out and you get the older runtime, where the code runs top to bottom and its last line is the result.
The markers in the code are read and attached when you push it: {{ ref('table-...') }} for an input table, {{ write(...) }} for an output table, {{ secret('secret-...') }} for a secret.
- A
{{ ref }}can name its table instead, as{{ ref('Sales.orders') }}or, in the same feature,{{ ref('orders') }}; Ronja stores the id, so a later rename can’t break the Workflow. A{{ ref }}that matches none of your tables’ ids or names is refused when you push, listing the names that would work. - A
{{ secret }}you can’t reach is dropped with a warning instead, and the run fails when it asks for the credential, so read thewarningsthe push returns. {{ write }}also takes a new table name, asweekly_salesabove, and creates the table.- A
{{ ref }}belongs inside the SQL you pass totools.query(...). Assigned to a variable, or read by a query the code runs itself, it saves and publishes, then fails on the first run.
4. Create and publish the App
Section titled “4. Create and publish the App”An App is created empty and unpublished, a draft only you can see. It gets its files, then a required validate step, then commit to publish it.
# Create the app. Declare every table/secret/workflow/agent it uses up front.rapi -X POST "$RONJA_BASE_URL/api/v2/dataapp" \ -d '{"featureID":"<feature-id>","name":"Weekly sales","allowedTableIDs":["table_..."]}'# -> 200 {"id":"dataapp_...", ...}
# Push the main file — App.tsx by default.rapi -X PUT "$RONJA_BASE_URL/api/v2/dataapp/dataapp_.../files/App.tsx" \ -d '{"content":"import { createRoot } from \"react-dom/client\";\nfunction App() { return <h1>Weekly sales</h1> }\ncreateRoot(document.getElementById(\"app\")).render(<App />);"}'# -> 200 {"dataAppID":"dataapp_...", "path":"App.tsx", ...}# The app's icon is PUT the same way, as files/icon.svg.
# Validate + compile the draft. Required before commit.rapi -X POST "$RONJA_BASE_URL/api/v2/dataapp/dataapp_.../validate"
# Commit to publish the app. The id does not change.rapi -X POST "$RONJA_BASE_URL/api/v2/dataapp/dataapp_.../commit"To see what the app does, POST /api/v2/dataapp/<id>/preview renders it headlessly and returns a screenshot, the errors it hit and the queries it ran. It is an observation, not a pass or fail, and it needs the Data scope because it runs the app’s real queries.
To take an app’s recommended updates, GET /api/v2/dataapp/:id/updates lists them, each with what to check afterwards, and POST /api/v2/dataapp/:id/rebuild rebuilds the app as your draft with them, leaving the live app alone. Preview the draft, fix what broke, then validate and commit it. Both need you to be able to make a draft of the app. The app-development guide linked from /llms.txt covers both, and the icon’s rules.
5. Share it
Section titled “5. Share it”Publishing makes the Workflow and the App live, but no one else can open them until you share the Feature: who can open anything in a Feature is decided by the Feature’s scope and, for an organization Feature, the access groups it is attached to. To share it in the web app instead, see Share and promote. People outside your organization open an App only once an Admin opens it to them; see Share apps with guests.
Build in a top-level Feature of your own. My Private Feature can never be shared, and a Saved Agent you create without naming a Feature lands there.
-
Preview the change. It changes nothing:
Terminal window rapi -X POST "$RONJA_BASE_URL/api/v2/feature/<feature-id>/scope-change-preview" \-d '{"requestedScope":"organization"}'# -> 200 {"violations":[], "canSelfApprove":true, "strandingWarnings":[], ...}Each entry in
violationslists itsblockers, usually a table or secret in another private Feature. Move them into this Feature and preview again. -
If
canSelfApproveistrue, share it withPOST /api/v2/feature/<feature-id>/promotion-directand the same body. OtherwisePOST /api/v2/feature/<feature-id>/promotion-requestwith{"requestedScope":"organization","note":"…"}asks for it, and nothing changes until an Admin approves.Where your organization has turned off self-approval, that has to be another Admin, even when you are one. Sharing in one step needs the Admin role: your own CLI sign-in carries your role, and only a Super Admin can create a token at the Admin role.
-
If the preview listed
strandingWarnings, the Feature is visible to admins only until it is attached to an access group. The API can’t attach it: an Admin does it in Ronja.
Check the result with GET /api/v2/feature/<feature-id>: scope reads organization. Don’t check it with the App’s commit response: its audience describes the Feature at that commit, so an App committed in step 4 still says author.
Gotchas
Section titled “Gotchas”-
Check a Workflow before you create it.
POST /api/v2/workflow/validatedry-runs a whole candidate Workflow, saves nothing, and returns every problem by file: unresolved markers, a missing or non-.pymain file, invalid parameters. Send theruntimeVersionyou are creating for (4); without it the dry run skips every runtime check. It doesn’t check whether you may write into a shared Feature. -
Declare what an App uses. The API doesn’t scan your source: declare an App’s
allowedTableIDs,allowedSecretIDs,allowedWorkflowIDsandallowedAgentIDsin the create body orPOST /api/v2/dataapp/:id/checkout. Only secrets are checked when it compiles, so an app whose SQL reads an undeclared table publishes cleanly and then shows no data. An emptyallowedTableIDsis the most common reason.capabilitiestakes onlyai,embed,query_external,write_externalandupload_file. Reading tables, secrets, Codexes, workflows, Saved Agents and metrics comes from theallowed…IDslists, so an App queries Ronja tables only when it lists one. A name Ronja grants on its own, such asquery_ronja, is ignored; any other name is refused with a 400. -
You can attach only what you can reach. Anything else is refused with a 400, because the App’s viewers inherit what it is attached to. An Admin reaches every live resource in the organization; anyone else reaches what their access groups reach.
-
An App’s main file must mount itself, ending with
createRoot(document.getElementById("app")).render(<App />). A file that only exports a component is refused. A name the source uses but never imports or defines is refused too, naming the file, line and name. Neither check proves the app renders: open it and look. -
Editing a published App starts a draft. The response’s
dataAppIDis where your edit landed; if it differs from the id you sent, the change is a draft until you validate and commit it. -
In a shared Feature, creating is for an Admin or a maintainer. Anyone else gets a 400 (
admin required to create a data app in a shared feature) fromPOST /api/v2/dataapp, and a refusedpublishon a new Workflow. Post a new App toPOST /api/v2/dataapp/propose, or a new Workflow toPOST /api/v2/workflow/propose, for an Admin to approve; both need the Admin scope.An edit to a published App or Workflow becomes a draft you submit with
POST /api/v2/dataapp/:id/request-revieworPOST /api/v2/workflow/draft/:id/request-review. Where self-approval is off, even a maintainer proposes a new App and submits an edit draft. Below the Admin role, propose from Ronja in a browser, or with a full-access personal access token such as the oneronja logingives you, which carries every scope. -
You author as the token’s user. A
privateFeature a token creates is its creator’s private Feature, and the token and that person can each work on what the other made inside it. The token is recorded as the creator and in the Activity log. An automation is owned by the token that created it, so only that token or an Admin can run it by hand. Anything a shared team token createsprivatelands in its creating Admin’s private Feature, so useorganizationscope for shared automation. -
A failed chain leaves orphans, and a retry gets
409 name_taken. No request spans Feature to Workflow to App. Feature names are unique in the organization and table names in their Feature, so re-sending a create that already succeeded is refused with a message naming the holder’s id. Keep each id you get back, and on a 409 carry on with the holder’s id.
Using Claude Code
Section titled “Using Claude Code”Drop this into your project’s CLAUDE.md so an AI coding assistant builds against the API correctly. It points at the live index, so it won’t go stale:
## Ronja API
Base URL: https://<your-org>.ronja.tech — every call sends `Authorization: Bearer $RONJA_API_TOKEN`.
Discover the API from the live index first: fetch `<base>/llms.txt`. It links to task recipesand the full endpoint list at `<base>/docs/api/endpoints.md` (every endpoint with its scope).Don't guess request bodies — read the OpenAPI spec at `<base>/docs/api/openapi.json`.
Golden path to build a Feature with a Workflow + App, then share it:0. GET /api/v2/policy/applied -> the organization's rules for HOW to build: follow `general.content`, then each `sections[].content`. Read-only for an API token.1. POST /api/v2/feature {name, scope} -> Feature id2. (optional) create + fill tables — see the "Send data" guide3. POST /api/v2/workflow/validate {featureID, entrypoint, files} (optional dry run) POST /api/v2/workflow {featureID, title, runtimeVersion: 4} -> draft PUT /api/v2/workflow/:id/files/main.py {content} (def main(...)) POST /api/v2/workflow/:id/publish -> live4. POST /api/v2/dataapp {featureID, name, allowedTableIDs} -> unpublished draft PUT /api/v2/dataapp/:id/files/App.tsx {content} (must end with createRoot(...).render(...)) POST /api/v2/dataapp/:id/validate (REQUIRED before commit) POST /api/v2/dataapp/:id/commit -> published (same id)5. POST /api/v2/feature/:id/scope-change-preview {requestedScope} POST /api/v2/feature/:id/promotion-direct {requestedScope} (when canSelfApprove) POST /api/v2/feature/:id/promotion-request {requestedScope, note} (else; an Admin approves)
Checklist:- Published is NOT shared: nobody else can open it until step 5. Report WHO can open it. strandingWarnings = an Admin must attach the Feature to an access group in Ronja.- Declare allowlists first; the API does NOT scan source. Only secrets are compile-checked: an undeclared table publishes clean and fails when someone opens the app.- A clean file write may carry `warnings` [{file, line, column, message}]: print them, never fail on them.- Editing a published App starts a draft; read `dataAppID` to see where the edit landed.- Shared Feature, neither Admin nor maintainer: a new App is a 400 (use POST /api/v2/dataapp/propose), a new Workflow's publish is refused (use POST /api/v2/workflow/propose), an edit is a draft for request-review.- No transaction spans the chain: keep every id, and on 409 name_taken continue with the holder.