Skip to content

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.

  1. Follow Create an API token. Name it (e.g. feature builder) and pick a Role that bounds what it can do.
  2. 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.
  3. Copy the secret from the Token created modal. It is shown only once.

Send it on every request as a Bearer token:

Terminal window
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.

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.

Terminal window
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.

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-...).

A Workflow is created as a draft, given its code, then published.

Terminal window
# 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 the warnings the push returns.
  • {{ write }} also takes a new table name, as weekly_sales above, and creates the table.
  • A {{ ref }} belongs inside the SQL you pass to tools.query(...). Assigned to a variable, or read by a query the code runs itself, it saves and publishes, then fails on the first run.

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.

Terminal window
# 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.

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.

  1. 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 violations lists its blockers, usually a table or secret in another private Feature. Move them into this Feature and preview again.

  2. If canSelfApprove is true, share it with POST /api/v2/feature/<feature-id>/promotion-direct and the same body. Otherwise POST /api/v2/feature/<feature-id>/promotion-request with {"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.

  3. 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.

  • Check a Workflow before you create it. POST /api/v2/workflow/validate dry-runs a whole candidate Workflow, saves nothing, and returns every problem by file: unresolved markers, a missing or non-.py main file, invalid parameters. Send the runtimeVersion you 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, allowedWorkflowIDs and allowedAgentIDs in the create body or POST /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 empty allowedTableIDs is the most common reason. capabilities takes only ai, embed, query_external, write_external and upload_file. Reading tables, secrets, Codexes, workflows, Saved Agents and metrics comes from the allowed…IDs lists, so an App queries Ronja tables only when it lists one. A name Ronja grants on its own, such as query_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 dataAppID is 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) from POST /api/v2/dataapp, and a refused publish on a new Workflow. Post a new App to POST /api/v2/dataapp/propose, or a new Workflow to POST /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-review or POST /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 one ronja login gives you, which carries every scope.

  • You author as the token’s user. A private Feature 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 creates private lands in its creating Admin’s private Feature, so use organization scope 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.

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 recipes
and 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 id
2. (optional) create + fill tables — see the "Send data" guide
3. 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 -> live
4. 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.