Skip to main content
PUT
Update Data Object
The Update Data Object endpoint allows you to modify an existing record in a dataset. You can update specific fields while leaving others unchanged. The API uses optimistic locking via the _version field to prevent concurrent modification conflicts.

Prerequisites

Authentication

Include your API key in the Authorization header.

Request

Path Parameters

string
required
The unique identifier of the business area. You can obtain this from the List Business Areas endpoint.
string
required
The unique identifier of the schema. You can obtain this from the List Schemas endpoint.
string
required
The unique identifier of the dataset. You can obtain this from the List Datasets endpoint.
string
required
The unique identifier of the data object to update. You can obtain this from the List Data Objects endpoint or from a previous create operation.

Headers

string
required
Your Pretectum API key. Create one in the Pretectum app under Configuration → API Keys.
string
required
Must be application/json.
string
default:"application/json"
The response content type. Currently only application/json is supported.

Request Body

integer
required
The current version of the data object. This must match the version currently stored in the system to prevent overwriting concurrent changes. You can get this value from List Data Objects, Get Data Object by Primary Key, or the create response (a newly created object starts at 0).
varies
The fields to update. Only include fields you want to change. Field names must match the schema field names exactly. Omitted fields remain unchanged.

Example Requests

Response

A successful update returns a 204 No Content response with no body.

Success Response

The 204 No Content response indicates the update was successful. The data object’s version is automatically incremented.

Error Responses

Optimistic Locking

The API uses optimistic locking to prevent concurrent modification conflicts:
  1. When you read a data object, note its _version value.
  2. Include this _version in your update request.
  3. If another process updated the object between your read and update, the versions won’t match and your update is rejected.
  4. On version conflict, re-read the data object to get the latest version and retry your update.

Version Conflict Response

A stale _version is rejected with 400 Bad Request and the code DATA_OBJECT_VERSION_CONFLICT. The record is left exactly as it was:
The check applies to every update, including one that changes the primary key value. A successful update increments _version by exactly one, so after a 204 you can send _version + 1 on the next update without re-reading, as long as nothing else writes to the record in between.

Partial Updates

You only need to include the fields you want to change. Omitted fields retain their current values:
This updates only the Status field while keeping all other fields unchanged.

Best Practices

  1. Always include _version: The version field is required for updates to prevent data conflicts.
  2. Handle version conflicts: Implement retry logic for scenarios where concurrent updates may occur.
  3. Update only changed fields: Send only the fields that need to be updated to minimize payload size.
  4. Validate before updating: Ensure updated values meet schema requirements before sending.
  5. Log update operations: Keep track of updates for audit purposes.

List Data Objects

Retrieve records and their versions

Create Data Object

Add new records to a dataset

Delete Data Object

Remove records from a dataset

Get Data Object by Primary Key

Fetch one record by its primary key value

Get Schema Details

View schema field definitions