Skip to navigation

/dataset/record

View as Markdown

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:

"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:

{
"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:

"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.

Request

This endpoint expects an object.
database_uuidstringRequired
internal_idintegerRequired
record_namestringRequired
record_uuidstringRequired
template_uuidstringRequired
metadata_for_uuidstringRequired
_record_metadataobjectRequired
fieldslist of objectsRequired
recordslist of anyRequired

Response headers

Access-Control-Allow-OriginstringOptional
Access-Control-Allow-MethodsstringOptional
Access-Control-Allow-HeadersstringOptional
Access-Control-Expose-HeadersstringOptional
Access-Control-Max-AgestringOptional
Cache-ControlstringOptional
X-Debug-TokenstringOptional
Keep-AlivestringOptional

Response

OK
database_uuidstring
internal_idinteger
record_namestring
record_uuidstring
template_uuidstring
metadata_for_uuidstring
_record_metadataobject
fieldslist of objects
recordslist of any