Create Entity

Creates a new Entity model (a content type) in your project’s schema, with its list of fields. Once created, you can start adding content of that type with POST /content.

This is the schema-management counterpart of the content endpoints: instead of creating an entry, it creates the type that entries belong to.

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.createModel(...). AI agents can reach it through the create-content-island-model MCP tool.

Endpoint

shell

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

Body

interface CreateEntityPayload {
  name: string; // model name (see "Name rules" below)
  fieldList: FieldSpec[]; // at least one field, in order
}

interface FieldSpec {
  id?: string; // omit when creating — the server assigns one
  name: string; // field name, unique within the model
  type: FieldType; // see "Field types" below
  relatedModelId?: string; // required for "relation" / "enum" types
  isArray?: boolean; // true → the field stores a list of values (default false)
  validations?: Validation[]; // see "Validations" below
}

interface Validation {
  name: string; // 'required' | 'unique' | 'min-length' | 'max-length' | 'media-type'
  customArgs?: any; // depends on the validation (see the table)
}

Name	Description
name	The model name. Must satisfy the name rules and be unique across the project’s models.
fieldList	The fields of the entity, in order. At least one field is required. Field order is preserved.

Field types

Each field’s type is one of the primitives below, or one of the two relational types.

type	Stores
short-text	A single line of text.
long-text	A multi-line / rich-text block.
number	A numeric value.
date	A calendar date.
date-time	A date together with a time.
media	A reference to an uploaded file (image, document, …).
boolean	true / false.
color	A color value.
relation	A reference to another entity. Requires relatedModelId.
enum	A reference to an enum. Requires relatedModelId.

Set isArray: true on any field to make it store a list of that type (e.g. an array of short-text tags, or a multi-relation).

Note

For relation and enum fields you send type plus the relatedModelId (the 24-character id of the target entity or enum). The server resolves it and assembles the stored composite type ("<id>|<Name>") for you — never build that composite string yourself. A relation must point at an entity; an enum field must point at an enum. Pointing the wrong type at the wrong target returns 400 VALIDATION_ERROR, and an unknown relatedModelId returns 404 NOT_FOUND.

Validations

Add validations to a field to constrain its values. They are stored when you create the model and enforced when content is saved or published.

name	customArgs	Enforced at
required	—	publish preflight
unique	—	save
min-length	{ "length": <number> }	publish preflight
max-length	{ "length": <number> }	publish preflight
media-type	{ "allowedExtensions": [{ "name": ".png", "category": "image" }, …] }	publish preflight

Caution

At the REST layer, media-type expects the canonical extension shape — each entry is { name, category } with a dotted extension name (.png) and one of the categories image · document · video · audio · code · compressed · font · other. (The create-content-island-model MCP tool is more forgiving — there you pass plain names like ["png","jpg"] and the server normalizes them.)

Name rules

A model name (and the same rules apply to field names) must:

• match the pattern /^[a-zA-Z0-9_ -]+$/ (letters, digits, spaces, _, -),
• be at most 128 characters,
• not be a reserved field-type word (short-text, long-text, number, date, date-time, media, boolean, color),
• be unique across the project’s models. Field names must be unique within the model (case-insensitive).

Example

A Article entity referencing an existing Author entity (relation) and a Size enum:

shell

curl -X POST https://api.contentisland.net/api/1.0/model/entity \
--header 'Authorization: Bearer YOUR_WRITE_TOKEN' \
--header 'Content-Type: application/json' \
--data '{
  "name": "Article",
  "fieldList": [
    {
      "name": "title",
      "type": "short-text",
      "validations": [
        { "name": "required" },
        { "name": "max-length", "customArgs": { "length": 120 } }
      ]
    },
    { "name": "body", "type": "long-text" },
    { "name": "views", "type": "number" },
    {
      "name": "cover",
      "type": "media",
      "validations": [
        {
          "name": "media-type",
          "customArgs": {
            "allowedExtensions": [
              { "name": ".png", "category": "image" },
              { "name": ".jpg", "category": "image" }
            ]
          }
        }
      ]
    },
    { "name": "tags", "type": "short-text", "isArray": true },
    { "name": "writtenBy", "type": "relation", "relatedModelId": "660f5b8a3a1c2d4e7f8b9012" },
    { "name": "size", "type": "enum", "relatedModelId": "660f5b8a3a1c2d4e7f8b34cd" }
  ]
}'

Response

On success the endpoint returns 201 Created with the id of the new model:

interface SaveModelResponse {
  id: string;
}

{
  "id": "660f5b8a3a1c2d4e7f8b9012"
}

Status Codes

Code	Description
201	The model was created. The response body contains the new model id.
400	Invalid payload — bad name (format / length / reserved / duplicate), empty fieldList, duplicate field names, or a relation/enum field pointing at the wrong target type.
401	Unauthorized. The token is missing, malformed or expired.
403	Forbidden. The token does not have write permissions — use a Write Token.
404	A relatedModelId does not match any model in the project.
500	Internal server error.