/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 `fields` array but does not yet exist on the record, it is created: the API assigns it a new numeric `id` and populates its `_field_metadata` block (including `_create_date`, `_update_date`, and `_create_auth`). - Fields that already exist (matched by `field_uuid`) have their values updated; their `id` and `_field_metadata` are 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_date` will 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, the `public_date` key 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: ```json "public_date": "2022-09-02 11:04:29" ``` 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`: ```json { "field_name": "Source ID", "field_uuid": "98c0dc4db715d503abc93fa598f9", "value": "Kleine_2018" } ``` 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: ```json "value": "" ``` 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.