v51

latestOpenAPI 3.0.1raw.githubusercontent.com2026-08-0118684573.2 KB

Entity Management

Updating an Entity

This endpoint is used to update the label or the properties (passed as JSON in the request body) of an Entity. You only need to include the properties you wish to update. To unset the value of any property, you can set it to empty string (""). The label must be a non-empty string. Setting a property to null will throw an error. Attempting to update a property that doesn't exist in the Dataset will throw an error.

Specifying a base version

You must either provide the query parameter baseVersion or use the force=true query parameter. The specified baseVersion must match the current version of the Entity on the server or the request will be rejected. This acts as a check to ensure you are not trying to update based on stale data. To update an Entity regardless of its current state, use the force flag with value true.

Resolving a conflict

You can also use this endpoint to resolve an Entity conflict by passing the resolve=true query parameter, in which case providing data in the request body is optional. When not providing new data, only the conflict status from the Entity will be cleared and no new version will be created. When providing data, the conflict will be cleared and an updated version of the Entity will be added.

patch/v1/projects/{projectId}/datasets/{name}/entities/{uuid}

Path parameters

projectIdnumber required

The numeric ID of the Project

namestring required

Name of the Dataset

uuidstring required

UUID of the Entity

Query parameters

baseVersioninteger

The base version of the Entity you are applying the update to (must match the latest version on the server)

forceboolean

Flag to forcefully update the Entity

resolveboolean

Flag to resolve the conflict

Response

uuidstring

The uuid of the Entity that uniquely identifies the Entity.

createdAtstring

ISO date format. The time that the server received the Entity.

updatedAtstring

Timestamp of the last update in ISO date format. null when there is only one version of the Entity.

deletedAtstring

Timestamp of the deletion in ISO date format. null if the Entity is not deleted.

creatorIdnumber

The ID of the Actor (App User, User, or Public Link) that originally created the Entity.

conflict'soft' | 'hard'

Type of the conflict.

hard: baseVersion conflicts and multiple versions update the same property

soft: baseVersion conflicts but data updates are independent

Example response

{
  "uuid": "uuid:85cb9aff-005e-4edd-9739-dc9c1a829c44",
  "createdAt": "2018-04-18T23:42:11.406Z",
  "updatedAt": "2018-04-18T23:42:11.406Z",
  "deletedAt": "2018-04-18T23:42:11.406Z",
  "creatorId": 1,
  "currentVersion": {
    "label": "John (88)",
    "current": true,
    "creatorId": 1,
    "userAgent": "Enketo/3.0.4",
    "version": 2,
    "baseVersion": 1,
    "branchId": "b0e927b6-958a-42f6-8344-1deb37ee9672",
    "trunkVersion": 1,
    "branchBaseVersion": 1,
    "data": {
      "firstName": "John",
      "age": "88"
    },
    "dataReceived": {
      "firstName": "John",
      "age": "88",
      "label": "John (88)"
    }
  }
}