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

create_data_entity

Adds a thing the system keeps records of, with its fields, so the data dictionary a brief implies is laid down as the conversation goes.

Add a data entity to a project's dictionary: project_id and name (singular, unique within the project) are required; plural, description (HTML), component_id, owner_id, pii (whether it holds personal data), retention_note and status (draft by default) fill in the record; fields lays down its columns in one go, each row with name (required), type (string by default, or text, integer, decimal, boolean, date, datetime, enum, uuid, json, file, reference), reference_entity_id for a reference, required, unique, pii, validation, example, description and enum_values for an enum. The entity is written through the same actions the Dictionary page runs: data_entity.created goes out and, with fields, data_entity.fields_changed.

Mark personal data as such on the entity and on each field: the guest view, the research sweep and the council read the flag. A staff token with data-entity:create on the project is needed.

Requires ability

data-entity:create

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

Runs the same actions as

POST/v1/projects/{project}/data-entitiesPUT/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.createddata_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

project_id*string

UUID of the project.

name*string

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; draft by default.

draftin_reviewapproveddeprecated

What it returns

{  "data": {    "id": "8c9d0e1f-2a3b-4c4d-8e5f-6a7b8c9d0e1f",    "project_id": "7f3d1c92-8b45-4e6a-9d21-5c8e0a4b6f13",    "component_id": null,    "name": "Order",    "plural": "Orders",    "description": "<p>One customer's laundry order, from placement to collection.</p>",    "owner_id": null,    "pii": true,    "retention_note": "Kept for seven years for the accounts, then anonymised.",    "status": "draft",    "position": 1,    "fields_count": 2,    "fields": [      {        "id": "9d0e1f2a-3b4c-4d5e-8f6a-7b8c9d0e1f2a",        "name": "reference",        "type": "string",        "reference_entity_id": null,        "required": true,        "unique": true,        "pii": false,        "validation": "SCL-ORD-000001",        "example": "SCL-ORD-000418",        "description": "The number the customer quotes.",        "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": "washing",        "description": "Where the order stands.",        "enum_values": ["received", "washing", "ready", "delivered"],        "position": 2      }    ],    "created_at": "2026-10-28T09:35:00+00:00",    "updated_at": "2026-10-28T09:35:00+00:00"  }}

How it fails

VALIDATION_FAILED

name missing or outside 2 to 80 characters, a name another entity of the project already uses, a status outside the four, more fields than allowed, a field without a name, a type outside the list, or a reference without an entity.

RESOURCE_NOT_FOUND

unknown project_id, or a project 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:create.

TOKEN_MISSING_ABILITY

token lacks data-entity:create.

Related

list_data_entitiesthe entities defined today.update_data_entitychange the record, the fields or the status.Data entities APIthe same doors over REST.

How is this guide?

Last updated on