Update Entity

Updates an existing Entity model: its name and the full set of fields. The body describes the desired final state of the model; the server reconciles it against the current model by field id.

Caution

This endpoint requires a Write Token in the Authorization header. Calling it with a regular (read) token returns 403 Forbidden.

Tip

If you’re using JavaScript or TypeScript, the Content Island API client wraps this endpoint as client.updateModel(...). AI agents can reach it through the update-content-island-model MCP tool, which offers a declarative (add / update / remove) interface on top of this endpoint.

How the reconciliation works

The fieldList you send is authoritative — it replaces the model’s field list, matched by id:

• a field with an existing id → that field is updated in place (rename, retype, change validations, …);
• a field without an id → a new field is appended;
• an existing field whose id is absent from the list → it is removed, and its values are deleted from every content of this type.

Danger

Because omitting a field removes it (and cascade-deletes its content values), always send the complete desired field list, keeping the id of every field you want to preserve. The recommended way to avoid mistakes is the update-content-island-model MCP tool, whose declarative addFields / updateFields / removeFieldIds operations compute the full list for you and gate removals behind a dry-run / confirm step.

The field shape (FieldSpec), field types, validations and name rules are identical to POST /model/entity — see that page for the full reference.

Endpoint

shell

curl -X PUT https://api.contentisland.net/api/1.0/model/entity/:id \
--header 'Authorization: Bearer YOUR_WRITE_TOKEN' \
--header 'Content-Type: application/json' \
--data '{ ... }'

Path Parameters

Name	Type	Required	Description
id	string	yes	The 24-character id of the entity to update.

Body

interface UpdateEntityPayload {
  name: string; // model name (may rename the model)
  fieldList: FieldSpec[]; // the complete desired field list, matched by id
}

Example

Rename Article → BlogArticle, keep title (note its id), add readingMinutes, and drop every other field by omitting it:

shell

curl -X PUT https://api.contentisland.net/api/1.0/model/entity/660f5b8a3a1c2d4e7f8b9012 \
--header 'Authorization: Bearer YOUR_WRITE_TOKEN' \
--header 'Content-Type: application/json' \
--data '{
  "name": "BlogArticle",
  "fieldList": [
    {
      "id": "770a6c9b4b2d3e5f8a9c0123",
      "name": "title",
      "type": "short-text",
      "validations": [
        { "name": "required" },
        { "name": "max-length", "customArgs": { "length": 200 } }
      ]
    },
    { "name": "readingMinutes", "type": "number" }
  ]
}'

Response

On success the endpoint returns 200 OK with the model id:

{
  "id": "660f5b8a3a1c2d4e7f8b9012"
}

Status Codes

Code	Description
200	The model was updated. The response body contains the model id.
400	Invalid payload — bad name, empty fieldList, duplicate field names, or a bad relation/enum target.
401	Unauthorized. The token is missing, malformed or expired.
403	Forbidden. The token does not have write permissions — use a Write Token.
404	No entity with the given :id exists in the project (or a relatedModelId is unknown).
500	Internal server error.