/dataset/record
POST a JSON record to persist changes to a dataset record in the API.
The request body mirrors the record structure returned by the GET endpoints. The API performs a delta update — only the fields included in the payload are evaluated. Existing fields not included in the payload are left unchanged.
Record-level behavior:
- If the record already exists (matched by
record_uuid), its field values are updated to reflect the submitted data. - If a field is included in the
fieldsarray but does not yet exist on the record, it is created: the API assigns it a new numericidand populates its_field_metadatablock (including_create_date,_update_date, and_create_auth). - Fields that already exist (matched by
field_uuid) have their values updated; theiridand_field_metadataare managed by the API and do not need to be provided.
Field metadata (_field_metadata):
Each field in the response includes a _field_metadata block populated by the API:
_create_date— timestamp when the field was first created_update_date— timestamp of the most recent update_create_auth— the authenticated user who created the field_public_date— controls field-level visibility; defaults to a far-future date (private)
Record metadata (_record_metadata):
The _record_metadata block on the record is read-only in normal operation and is managed by the API. It reflects:
_create_date— when the record was first created_update_date— updated automatically on every successful POST_create_auth— the user who originally created the record_public_date— controls record-level visibility
Optional parameters:
created— Include in a record block or field block to set a custom creation date when creating a new record or field. The_update_datewill also be set to this value.public_date— Include in a record block or a file/image data block to make the record, image, or file publicly visible at the specified date. For files and images, thepublic_datekey is consumed by the API (removed from the payload) and the corresponding metadata object is updated.
File and image fields:
Files and images are nested within their field’s files array. To update the public_date of a file or image, include a public_date key in the file/image data block:
The API removes this key from the stored data and updates the file/image metadata to reflect the new public date.
Nested records:
Child records can be included in a records array within the parent record. Each child record follows the same structure and update rules as the top-level record.
Scalar / text field updates (value parameter):
Several datatypes store their content as a single value string directly on the field object. To update these fields, include the field in the fields array with the field_uuid and the new value:
Datatypes that use the value parameter include (but may not be limited to):
- Short/Long Text — free-form string content
- Integer — numeric whole-number value stored as a string
- Decimal — floating-point numeric value stored as a string
- Paragraph / Markdown — multi-line text content (e.g., a BibTeX citation block)
To clear a value field, submit an empty string:
The id and _field_metadata properties are optional when updating an existing field — the API manages them internally. Only field_uuid and value are required to perform an update.
