Documentation
Product GuideREST API ReferenceMCP Server for AI AgentsWebhooks & EventsIntegrations
DESTRUCTIVE

update_data_entity

Changes a data entity in part, replaces its fields when a list is sent and moves it along its review when a status is sent.

Change a data entity by data_entity_id with any of name, plural, description (HTML), component_id, owner_id, pii, retention_note, fields and status (draft, in_review, approved or deprecated; a move the lifecycle allows). A field left out keeps its value; a field sent as null is cleared. fields replaces the list: a row with an id keeps and changes that field, a row without one is new, and a field left out of the list goes. The record goes through the update action, the fields through the sync and the status through its own move, so data_entity.updated, data_entity.fields_changed and data_entity.status_changed go out as each applies. A staff token with data-entity:update on the project is needed.

Requires ability

data-entity:update

The token behind the MCP session must hold it, or the call is refused with TOKEN_MISSING_ABILITY.

Runs the same actions as

PATCH/v1/data-entities/{entity}POST/v1/data-entities/{entity}/statusPUT/v1/data-entities/{entity}/fields

The REST endpoint and this tool share one action, so validation, permissions and events are identical.

Fires events

data_entity.updateddata_entity.status_changeddata_entity.fields_changed

Delivered to every endpoint subscribed to it once the change is made.

Annotations

Destructive

A client that honours annotations asks a person before running it.

Arguments

data_entity_id*string

UUID of the data entity.

namestringoptional

What the entity is called, in the singular, 2 to 80 characters.

pluralstringoptional

The plural, when it is not the name with an s.

descriptionstringoptional

What the entity is and what it is for, as HTML.

component_idstringoptional

UUID of the component whose records these are.

owner_idstringoptional

UUID of the team member who answers for it.

piibooleanoptional

Whether it holds personal data.

retention_notestringoptional

How long records are kept and why.

fieldsarrayoptional

The fields, replacing the current list: objects with name (required), type (string, text, integer, decimal, boolean, date, datetime, enum, uuid, json, file, reference), reference_entity_id, required, unique, pii, validation, example, description and enum_values; a row with an id keeps that field.

statusstringoptional

Where the entity stands in review; a move the lifecycle allows.

draftin_reviewapproveddeprecated

What it returns

{  "data": {    "id": "8c9d0e1f-2a3b-4c4d-8e5f-6a7b8c9d0e1f",    "project_id": "7f3d1c92-8b45-4e6a-9d21-5c8e0a4b6f13",    "component_id": "c0a1b2c3-d4e5-4f60-8a7b-9c0d1e2f3a4b",    "name": "Order",    "plural": "Orders",    "description": "<p>One customer's laundry order, from placement to collection.</p>",    "owner_id": "5b6c7d8e-9f0a-4b1c-8d2e-3f4a5b6c7d8e",    "pii": true,    "retention_note": "Kept for seven years for the accounts, then anonymised.",    "status": "in_review",    "position": 1,    "fields_count": 3,    "fields": [      {        "id": "9d0e1f2a-3b4c-4d5e-8f6a-7b8c9d0e1f2a",        "name": "reference",        "type": "string",        "reference_entity_id": null,        "required": true,        "unique": true,        "pii": false,        "validation": null,        "example": "SCL-ORD-000418",        "description": null,        "enum_values": [],        "position": 1      },      {        "id": "0e1f2a3b-4c5d-4e6f-8a7b-8c9d0e1f2a3b",        "name": "status",        "type": "enum",        "reference_entity_id": null,        "required": true,        "unique": false,        "pii": false,        "validation": null,        "example": null,        "description": null,        "enum_values": ["received", "washing", "ready", "delivered"],        "position": 2      },      {        "id": "1f2a3b4c-5d6e-4f7a-8b8c-9d0e1f2a3b4c",        "name": "customer",        "type": "reference",        "reference_entity_id": "2a3b4c5d-6e7f-4a8b-8c9d-0e1f2a3b4c5d",        "required": true,        "unique": false,        "pii": false,        "validation": null,        "example": null,        "description": "The customer who placed it.",        "enum_values": [],        "position": 3      }    ],    "created_at": "2026-10-28T09:35:00+00:00",    "updated_at": "2026-10-28T16:40:00+00:00"  }}

How it fails

VALIDATION_FAILED

a field outside its limits, a name another entity of the project already uses, a row without a name, a type outside the list, a reference without an entity, or a move the lifecycle does not allow from where the entity stands.

RESOURCE_NOT_FOUND

unknown data_entity_id, or an entity outside the token's scope or the person's visibility.

FORBIDDEN

the token is a client guest's, or the holder's role on the project does not carry data-entity:update.

TOKEN_MISSING_ABILITY

token lacks data-entity:update.

Related

get_data_entitythe entity with its fields as they stand.delete_data_entitytake it away.Data entities APIthe same doors over REST.

How is this guide?

Last updated on