Grist Octri Preview
PUT/docs/{docId}/tables/{tableId}/records

Add or update records in a table

Adds or updates records in a table by matching each record's require values against existing rows and applying fields to matches. If no match exists, creates a record using values from both objects, with fields taking precedence when a column appears in both. Use noadd, noupdate, onmany, or allow_empty_require to alter this behavior; allowing an empty require matches all records.

7 parameters · 1 body field
docIdstringrequired
The document identifier, as a UUID string.
tableIdstringrequired
The normalized table name or numeric row ID in `_grist_Tables` identifying the table.
noparsebooleanoptional
Set to `true` to prevent strings from being parsed according to the column type.
onmanystringoptional
Controls which matching records are updated when multiple records match `require`: `first`, `none`, or `all`. Defaults to `first` when omitted.
Allowed:firstnoneall
noaddbooleanoptional
Set to `true` to prevent adding records.
noupdatebooleanoptional
Set to `true` to prevent updating records.
allow_empty_requirebooleanoptional
Set to `true` to allow an empty `require` to match and update all records in the table.

The records to add or update. Each record uses require to match existing rows and may use fields to specify values to set.

recordsarray<object>required
The records to process. Each record must include `require`, and may include `fields`.

1 status code
200Returns a success response confirming the records operation completed.

Error handling

The request body must include records, and each record must include require; fields contains the column values to set or update. The onmany query parameter accepts first, none, or all and defaults to first when omitted. Set the allow_empty_require query parameter to true only if you intend an empty require to match and update all records in the table.