Records: Update

Description

Update a record's field values and/or re-parent it. Field and re-parent changes commit together in a single transaction. The updated record is returned in the same data / field_ids envelope as the Get record API.

See the Get record API to learn more about records.

Request

HTTP Method: PATCH

URL: https://<tenant-domain>/api/v2/records/<<record_id>>

Path parameter	Description
id	The ID of the record to update.

The request body is a JSON object with the following fields:

Body parameter	Required	Description
field_values	No	An array of field values to set (see Field values). Fields you omit keep their current value.
parent_id	No	Re-parent the record under this record ID. Send null to detach it from its parent; omit to leave the parent unchanged.
test_mode	No	Optional JSON boolean guardrail sent in the request body. For an authorized write, a mismatch returns 422: true requires a test record, false a live record. Omit to update regardless of mode.

An unknown body or query parameter returns a 400. The request must set at least one field value or include parent_id; an empty body or field_values: null returns a 400. An empty field_values array is valid only when parent_id is also present, including null to detach the record.

Field values

Each entry in field_values sets one field and takes one of field_id or field_name, never both, and each field may appear at most once:

Key	Required	Description
field_id or field_name	Yes	The field to set, by numeric field_id or by field_name (its name or slug; matching is insensitive to case and separators).
value	Yes	The field's typed value. Send null to clear the field.

Fields omitted from field_values keep their current value — an update is a partial merge, not a replace. value holds the field's typed value: a string, number, boolean, or ISO 8601 timestamp for scalar fields; a JSON object or array for JSON fields; and a (large) text string for ARTIFACT fields.

Timestamps. TIMESTAMP field values are stored in UTC; v2 converts an offset you send to the equivalent UTC instant. Send a Z-suffixed UTC timestamp to avoid ambiguity.

Example request

curl --proto '=https' --tlsv1.2 \
  -X PATCH \
  "https://<tenant-domain>/api/v2/records/<<record_id>>" \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <<CREDENTIAL.tines_api_key>>' \
  -d '{
    "field_values": [
      { "field_name": "status", "value": "closed" }
    ],
    "parent_id": null
  }'

Response

A successful request returns 200 OK with a JSON object containing a data object representing the updated record and a field_ids map.

Field description

Field	Description
data	The updated record object (same shape as the Create record API response).
field_ids	Map of each returned field's slug key to its immutable field ID, so callers can pin to the ID across renames.

As with create, JSON and ARTIFACT field values are returned as a handle — follow its href with the Get record field API to retrieve the full value.

Sample response

{
  "data": {
    "id": 556,
    "fields": {
      "status": "closed"
    },
    "relationships": {
      "record_type": {
        "id": 42
      },
      "parent_record": null
    },
    "created_at": "2026-07-02T00:00:00Z",
    "updated_at": "2026-07-06T12:30:00Z"
  },
  "field_ids": {
    "status": 101
  }
}

Errors

Errors are returned as a JSON object with an error field, along with an appropriate HTTP status code:

{
  "error": {
    "type": "not_found",
    "message": "Record not found"
  }
}

Status	Meaning
400	Invalid request — a malformed record ID or body, an unknown parameter, an invalid or duplicated field reference, or a blank parent_id.
403	The tenant does not have access to records, or the caller lacks permission to update this record.
404	Record not found, or the calling token does not have access to it.
408	The write timed out. Retry the request.
422	The record could not be updated — for example the record type is not editable, a field value failed validation (including an impossible timestamp date or object/array for a non-JSON field), re-parenting would create a cycle or cross modes, or the test_mode guardrail did not match the record's mode.

The error object always carries type and message; validation errors add a field pointer, and some add a hint suggesting a correction.