Send data via the API

Who can do this

Creating API tokens requires Admin. Pushing files requires a token whose role is Data Admin or higher — and, for a scoped token (one limited to specific permission areas), the Data scope set to Write.

Create an API token

1. Open API Tokens in the admin sidebar (under Platform & Integrations).
2. Click Create New. In the Create token modal, name the token (e.g. CI pipeline) and pick a Role — the role bounds everything the token can do.
3. Keep the access setting on Limited to scopes (the default) and grant only what your integration needs: each scope (Data, Structure, Analytics, Automation, Agents, Secrets, Admin) can be None, Read, or Write. Full access skips scope limits entirely and shows a red warning — prefer Limited.
4. Click Create token and copy the secret from the Token created modal.

“Copy this token now — you won’t be able to see it again.”

Caution

The secret is shown exactly once; only a hash is stored. If you lose it, delete the token and mint a new one.

Send the token on every request in the Authorization header. The interactive API reference lives in the app under Documentation (/admin/docs/api); a summary is in the API reference.

Push data files

The file push API feeds a manual-integration table — a table whose data you push from your own systems instead of syncing through a connection. It accepts Parquet files only, sent as a raw request body (never multipart), up to 1 GiB per file. Convert CSV first, for example:

python -c "import pandas as pd; pd.read_csv('sales.csv').to_parquet('sales.parquet')"

1. Create the table once — featureID, the feature that will own the table, is a required body field alongside name. The response contains the table ID, table_…, which also appears in the table’s URL in the app:

   curl -X POST "$RONJA_BASE_URL/api/v2/feature/model" \
     -H "Authorization: $RONJA_API_TOKEN" \
     -d '{"name":"sales_pushes","kind":"manual_integration","featureID":"<your feature ID>"}'

2. Upload a file:

   curl -X PUT \
     "$RONJA_BASE_URL/api/v2/feature/model/table_a1b2c3d4e5/file/sales_2026.parquet" \
     -H "Authorization: $RONJA_API_TOKEN" \
     --data-binary @./sales_2026.parquet
   # -> 200 {"filename":"sales_2026.parquet","size":48230}

   Re-uploading the same filename replaces the previous file; different filenames accumulate and are built together.

3. List or delete files as needed:

   curl "$RONJA_BASE_URL/api/v2/feature/model/table_a1b2c3d4e5/files" \
     -H "Authorization: $RONJA_API_TOKEN"
   curl -X DELETE \
     "$RONJA_BASE_URL/api/v2/feature/model/table_a1b2c3d4e5/file/old.parquet" \
     -H "Authorization: $RONJA_API_TOKEN"

4. Build to make the data queryable — uploading alone is not enough:

   curl -X POST "$RONJA_BASE_URL/api/v2/feature/model/table_a1b2c3d4e5/build" \
     -H "Authorization: $RONJA_API_TOKEN"

   The build runs asynchronously; poll GET /api/v2/feature/model/table_a1b2c3d4e5 until status is "ready". The schema is detected automatically from the Parquet files.

Caution

Do not upload with multipart form flags (curl -F) — the endpoint reads the raw body, so a multipart envelope fails Parquet validation with “uploaded file is not a valid parquet file”. Use --data-binary as shown. Filenames must match [a-zA-Z0-9._-]+.parquet; files over 1 GiB are rejected with a 413.

$RONJA_BASE_URL is your organization’s Ronja URL. Tokens are bound to your organization — a token from one organization can never read or write another’s tables.