Skip to main content

Creating Entities

The Gateway provides an endpoint to create entities in the database.

info

If you want to upload files, see Upload Files.

info

If you are importing data from external sources into our system, have a look at Remote Identifiers.

Request​

POST 
/api/v1/entities
{
  "entity": {
    "types": [
      "schema:Event"
    ],
    "project": "66f3d1e6382ece6f7570ff3c",
    "content": {
      "schema:name": [
        {
          "value": "Gamescom 2077",
          "lang": "de-DE"
        }
      ]
    }
  },
  // Not required, see below for more information
  "options": {}
}

This request will create a new entity with the type schema:Event and the name Gamescom 2077.

info

Have a look at Multi Lang Text for more information about the language tag format (lang).
Also note that you can only use languages that are available for the project in which you want to create the entity.

Entity (entity)​

Every created entity needs to have at least the following properties:

  • types: An array of types the entity belongs to. The first type is the main type.
  • project: The project ID the entity will belong to.
  • content: The content of the entity. This is a JSON object with the properties of the entity.

Additionally, these properties can be set:

  • channels: An array of channel IDs the entity will be available in.
  • pools: An array of pool IDs the entity will be available in.

The content is validated against our datamodel and needs to follow the schema of the entity type. Here you can find some extensive example entities that provides many possible properties that you might want to use.

Options (options)​

"selfCorrect": boolean (default: false)
If set to true, the Gateway will try to correct the entity if it is not valid.

"setInitValue": boolean (default: false)
If set to true, the Gateway will set the initial value for all properties that are not set.

"ignoreUnknownFields": boolean (default: false)
If set to true, the Gateway will ignore unknown fields in the entity. Otherwise, the Gateway will return an error if unknown fields are present.

Response​

The response will look like this:

{
  "status": "success",
  "entity": {
    "_id": "6798b7b709256629566d21bd",
    "types": [
      "schema:Event"
    ],
    "types_all": [
      "schema:Event",
      "schema:Thing",
      "schema:Intangible"
    ],
    "schema:name": [
      {
        "value": "Gamescom 2077",
        "lang": "en"
      }
    ]
  },
  "protocol": {}
}

Status (status)​

  • success: The entity was created successfully.
  • error: An error occurred.
  • requires_action: The entity was created, but some properties were not set correctly. The Gateway will return a list of properties that need to be corrected.

Protocol (protocol)​

The protocol is an object that contains additional information about the entity creation. If the entity could not be created, the protocol will contain all errors that occurred.

For example, if we try to create the same entity without a project and remove the language from the name.

{
  "entity": {
    "types": [
      "schema:Event"
    ],
    "content": {
      "schema:name": [
        {
          "value": "Gamescom 2077"
        }
      ]
    }
  }
}

The response will look like this:

{
  "status": "error",
  "entity": {
    "types": [
      "schema:Event"
    ],
    "content": {
      "schema:name": [
        {
          "value": "Gamescom 2077"
        }
      ]
    }
  },
  "protocol": {
    "project": {
      "level": "error",
      "error": "missing_value",
      "description": "The field 'project' is required and can't be empty. Please provide a value!"
    },
    "content": {
      "schema:name": {
        "level": "error",
        "error": "invalid_value",
        "description": "The given data doesn't match the MultiLang structure, example: [{'lang': 'de-DE', 'value': 'Name DE'}]"
      }
    }
  }
}

For more information about the protocol see the Validation Protocol.