API reference
This page is the lookup summary. For the end-to-end walkthrough with examples, see Send data via the API. The interactive endpoint-by-endpoint API reference is served at /docs/api on your Ronja domain.
API tokens
Section titled “API tokens”Tokens are created by an Admin on the API Tokens page (page title “Tokens”): click Create New.
| Create field | Details |
|---|---|
| Name | A label, e.g. “CI pipeline” |
| Role | Every token is bound to a role (default User); the role bounds everything the token can do. An admin cannot mint a token at or above their own role level |
| Access | Limited to scopes (recommended default — grant at least one scope) or Full access (unrestricted within its role; a warning is shown) |
- The token secret is shown exactly once at creation (“Copy this token now — you won’t be able to see it again.”). It cannot be re-displayed — only revoked.
- Send it as a bearer token:
Authorization: Bearer <token>(theBearerprefix is optional). - Tokens are bound to your organization and can be revoked at any time from the token list or detail page.
Token scopes
Section titled “Token scopes”Scopes narrow a token within its role — they never widen it. Each scope is granted at None, Read, or Write. A scoped token is denied on anything outside its grants.
| Scope | Covers |
|---|---|
| Data | Tables, files, connectors & search |
| Structure | Features & workspaces |
| Analytics | Data apps, notes & knowledge |
| Automation | Workflows, schedules & scripts |
| Agents | AI agents, chat & MCP |
| Secrets | Secrets & OAuth connections |
| Admin | Members, billing, governance & settings |
A token can later be restricted to scopes, or widened back to full access (confirm-gated), from its detail page.
File push API
Section titled “File push API”Push data files into a manual-integration table — Integration tables fed by files instead of a connector. Requires a token whose role has Data Admin rights and (if scoped) Data: Write; listing files only needs read access.
Format: Parquet only. Filenames must match [a-zA-Z0-9._-]+.parquet; convert CSV to Parquet client-side first.
| Step | Endpoint | Notes |
|---|---|---|
| 1. Create the table (once) | POST /api/v2/feature/model with {"name":"...","featureID":"...","kind":"manual_integration"} |
featureID goes in the body, not the path. Returns the table ID (table_…), also visible in the table’s URL |
| 2. Upload a file | PUT /api/v2/feature/model/{tableID}/file/{filename} |
Raw body (not multipart), max 1 GiB per file. Re-uploading the same filename replaces it; different filenames accumulate and build together |
| 3. List files | GET /api/v2/feature/model/{tableID}/files |
Paginated (200 per page, nextCursor) |
| 4. Delete a file | DELETE /api/v2/feature/model/{tableID}/file/{filename} |
404 if the file doesn’t exist |
| 5. Build | POST /api/v2/feature/model/{tableID}/build |
Required — uploads alone are not queryable. Async: poll GET /api/v2/feature/model/{tableID} until status is ready |
The table’s schema is auto-detected from the Parquet files.
Error responses
Section titled “Error responses”Bodies are always {"error": "<message>"}.
| Status | Message | Cause |
|---|---|---|
| 401 | Unauthorized |
Missing or invalid token |
| 403 | forbidden |
Role below Data Admin, or a scoped token without the Data: Write grant |
| 400 | invalid filename: must match [a-zA-Z0-9._-]+.parquet |
Bad filename |
| 400 | model is not a manual_integration table |
Wrong table kind |
| 400 | no rows: ... |
Nonexistent table ID (returned as 400, not 404) |
| 400 | uploaded file is not a valid parquet file / uploaded parquet file has no columns |
Content failed validation; the upload is discarded |
| 404 | file not found |
DELETE on a missing file |
| 413 | file too large: max 1073741824 bytes |
Over 1 GiB — split the file client-side |