# Ninox

Create, find, update and delete records in Ninox databases, attach and download files, and run Ninox scripts.

## Connect Ninox

1. In the sidebar, open **Connections** and press **Add connection**.
2. Type `ninox` and choose **Ninox**.
3. Fill in the fields. Each one says **Required** or **Optional**.
4. Press **Test and save**. GoRunner checks the connection before it saves anything.

The sheet asks for:

- **API key · Required**: The key from Ninox › Integrations.
- **Server address · Optional**: Only for a Private Cloud or an on-premises server: its address (https://\<name>.ninoxdb.de, or your own host). Empty uses Ninox’s public cloud.

A Ninox API key: in Ninox open the gear menu › Integrations and generate a key (team owners only; in a Private Cloud, its /admin page › API keys, with the role the workflows need). For a Private Cloud or an on-premises server also enter its address.

[Connections](https://docs.gorunner.io/build/connections) says how to sign in again, rename or delete it. In a product that embeds GoRunner, **Add connection** can be missing: then [your provider makes connections](https://docs.gorunner.io/embed/customer-connections) for you.

## Start a workflow

Add a trigger and choose **Ninox**. The trigger uses the same connection as the steps.

### On Record Added or Changed

Checks a Ninox table about once a minute and starts a run for each record added (or changed) since the check before. The first check after publishing only takes note of what is there (it starts nothing); changing the trigger starts over the same way. Each change starts one run, at most 100 a minute (the rest follow the minute after); a record changed twice between checks starts one run with its latest values.

- **Team · Required**: The Ninox team (workspace) the database is in.
- **Database · Required**: The database.
- **Table · Required**: The table.
- **Trigger on · Required**: What starts a run. Options: Record added, Record added or changed. Default: Record added.

A later step can use its data, such as `{{trigger.change_type}}`, `{{trigger.createdAt}}`, `{{trigger.fields}}` and 3 more. See [Use data from earlier steps](https://docs.gorunner.io/build/use-data-from-earlier-steps).

## Do things in Ninox

Add a **Ninox** step, choose a **Resource**, then an **Operation**. Choose a row to see its fields.

- [Record](https://docs.gorunner.io/apps/ninox#fields-f-record): Create · Get · Get Many · Update · Delete
- [File](https://docs.gorunner.io/apps/ninox#fields-f-file): Upload · Get Many · Download · Delete
- [Database (script)](https://docs.gorunner.io/apps/ninox#fields-f-database): Run Query (read only) · Run Script (may change data)

Later steps read a step’s output by its name: see [Use data from earlier steps](https://docs.gorunner.io/build/use-data-from-earlier-steps).

## Limits

- A reply from Ninox can be up to 16 MB (a file download can have its own limit). A larger one fails the step; it is never cut short.
- When Ninox says to slow down (429), the step waits as long as it asks, if the step’s time allows. Otherwise it fails and says when to try again.

Not in your list? See [When an app isn’t here](https://docs.gorunner.io/apps/when-an-app-isnt-here#q-not-in-list).

## For developers

In the API, which calls apps pieces, Ninox is `pieceId: "ninox"` with `actionId: "ninox"`, set by `resource` and an `operation_…` field, such as `operation_database`. Its trigger is `ninoxtrigger` / `ninox_poll`. [Get an app](https://docs.gorunner.io/api/apps/get-app) returns every field.

It can change something outside the run (`writes_external`). See [How versions and side effects work](https://docs.gorunner.io/apps#q-versions).

### Ninox › Record

### Create

- **Team · Required**: The Ninox team (workspace) the database is in.
- **Database · Required**: The database.
- **Table · Required**: The table.
- **Fields · Required**: Values by field name, such as {"Name": "Müller GmbH", "City": "Hamburg", "Customer since": "2026-11-01"}. An update changes only the fields given.

### Get

- **Team · Required**: The Ninox team (workspace) the database is in.
- **Database · Required**: The database.
- **Table · Required**: The table.
- **Record ID · Required**: The record's number (its id in Ninox).
- **Choice Values · Optional**: Whether choice fields come back as their option names or their ids. Options: Names, Ids. Default: Names.

### Get Many

- **Team · Required**: The Ninox team (workspace) the database is in.
- **Database · Required**: The database.
- **Table · Required**: The table.
- **Filters · Optional**: Only records whose fields have these values, by field id, such as {"C": "Hamburg", "E": "Customer"}. Empty reads every record.
- **Order · Optional**: The order records come in. Options: By record id, Newest first, Last changed first, By a field. Default: By record id.
- **Choice Values · Optional**: Whether choice fields come back as their option names or their ids. Options: Names, Ids. Default: Names.
- **Order By Field · Required**: The field name to order by. Shows when **Order** is **By a field**.
- **Descending · Optional**: Largest or latest value first. Off by default. Shows when **Order** is **By a field**.
- **Return All · Optional**: Read every record, page by page (at most 2000; past that the step fails rather than stop early). Off by default.
- **Limit · Optional**: How many records to return (1–2000). Default: 50. Shows when **Return All** is off.

### Update

- **Team · Required**: The Ninox team (workspace) the database is in.
- **Database · Required**: The database.
- **Table · Required**: The table.
- **Record ID · Required**: The record's number (its id in Ninox).
- **Fields · Required**: Values by field name, such as {"Name": "Müller GmbH", "City": "Hamburg", "Customer since": "2026-11-01"}. An update changes only the fields given.

### Delete

- **Team · Required**: The Ninox team (workspace) the database is in.
- **Database · Required**: The database.
- **Table · Required**: The table.
- **Record ID · Required**: The record's number (its id in Ninox).

### Ninox › File

### Upload

- **Team · Required**: The Ninox team (workspace) the database is in.
- **Database · Required**: The database.
- **Table · Required**: The table.
- **Record ID · Required**: The number of the record the file belongs to.
- **File · Required**: Upload a file, or switch to an expression to use one from an earlier step (such as {{steps.download.result}}). At most 11 MB.

### Get Many

- **Team · Required**: The Ninox team (workspace) the database is in.
- **Database · Required**: The database.
- **Table · Required**: The table.
- **Record ID · Required**: The number of the record the file belongs to.

### Download and Delete

- **Team · Required**: The Ninox team (workspace) the database is in.
- **Database · Required**: The database.
- **Table · Required**: The table.
- **Record ID · Required**: The number of the record the file belongs to.
- **File Name · Required**: The attached file's name, as Get Many lists it.

### Ninox › Database (script)

### Run Query (read only) and Run Script (may change data)

- **Team · Required**: The Ninox team (workspace) the database is in.
- **Database · Required**: The database.
- **Script · Required**: A Ninox script, such as (select Customers where City = "Hamburg").Name. Data from earlier steps is never pasted into it: to look records up by a value from an earlier step, use Record › Get Many with Filters.

Source: https://docs.gorunner.io/apps/ninox