Create entity instance

POST/projects/{projectId}/entities

Base URL: https://api.tinkermode.com

Create a new entity instance.

Authentication

Send an Authorization header of the form ModeCloud <AUTH_CODE>.

Must contain a user API key of a user with permission to create child entities on the parent entity, a service account token with the same permission, or a project API key with admin permission.

Path parameters

Name	Type	Required	Constraints	Description
`projectId`	integer	Yes		The unique ID for a specified project.

Request body

Content type: application/json

Property	Type	Required	Description
`attributes`	object	No	The attributes that belong to the entity instance, separated as key-value pairs.
`displaySettings`	object	Yes	Various user interface settings used for display of the entity class. This object must contain at least the `name` field.
`entityClass`	string	Yes	The entity class that the entity will be instantiated from.
`entityId`	string	Yes	Unique entity ID.
`homeId`	number	Yes	Home that this entity belongs to.
`parentId`	string	No	The ID of the entity instance that is a parent of the instance.
`timeZone`	string	Yes	The time zone that the entity exists in. This should be a time zone name defined in the IANA TZ Database.
`uiSettings`	object	No	An opaque object used by UI applications to store any additional settings. These will override the entity class uiSettings.

Responses

`201` Successful creation of entity instance.

Content type: application/json

Property Type Required Constraints Description

attributes object No The attributes that belong to the entity instance, separated as key-value pairs.

createdAt string No read-only (server-generated); format: date-time Timestamp of entity creation.

displaySettings object No Various user interface settings used for display of the entity instance.

Property Type Required Constraints Description

description string No An intuitive description for the entity instance for display.

iconData object No Metadata used for the uploaded icon of the entity instance.

Properties of iconData
Property	Type	Required	Constraints	Description
`fileName`	string	No		FileName represents the name of the file uploaded.
`url`	string	No		A temporary signed URL for file download.

imageData object No Metadata used for the uploaded image of the entity instance.

Properties of imageData
Property	Type	Required	Constraints	Description
`fileName`	string	No		FileName represents the name of the file uploaded.
`url`	string	No		A temporary signed URL for file download.

name string No The display name for the entity instance.

entityClass string Yes read-only (server-generated) The entity class that the entity was instantiated from.

entityId string Yes read-only (server-generated) Unique entity ID.

homeId integer Yes read-only (server-generated) Home that this entity belongs to.

metrics array<object> No read-only (server-generated) Meta data of the metrics associated with this entity instance.

Properties of metrics
Property	Type	Required	Constraints	Description
`metricsDefinitionId`	string	No		Corresponding metrics definition ID in entity class.

parentId string No The ID of the entity instance that is a parent of the instance.

projectId integer Yes read-only (server-generated) Project that this entity belongs to.

suspendAlertRuleEvaluationConditions array<object> No An array of condition for suspending alerts, which are evaluated as if they are concatenated with OR

Properties of suspendAlertRuleEvaluationConditions
Property	Type	Required	Constraints	Description
`alertConditionTypes`	array<string>	No		An array of alert condition types. This allows suspending alerts based on the alert types. All rules of the specified condition type will be suspended.
`from`	string	No	format: date-time	Timestamp of the begin of the interval. Null applies this rule without this time constrains
`includeDescendants`	boolean	No		Boolean value that shows whether alert rules are suspended for only this entity or this entity and descendants
`rules`	array<number>	No		An array of alertRuleId. Empty array means all rules
`to`	string	No	format: date-time	Timestamp of the end of the interval. Null applies this rule without this time constrains

timeZone string Yes read-only (server-generated) The time zone that the entity exists in. This should be a time zone name defined in the IANA TZ Database.

uiSettings object No An opaque object used by UI applications to store any additional settings. These will override the entity class uiSettings.

updatedAt string No read-only (server-generated); format: date-time Timestamp of the last update on the entity.

Response example

{
  "attributes": {
    "group": "samsung_freezer_model_4",
    "minTemperatureCelsius": -40.2
  },
  "createdAt": "2021-09-02T22:19:39Z",
  "displaySettings": {
    "description": "A warehouse freezer in warehouse room #003.",
    "iconData": {
      "fileName": "freezer_icon.png",
      "url": "https://example.com/icons/freezer_icon.png"
    },
    "imageData": {
      "fileName": "freezer.png",
      "url": "https://example.com/images/freezer.png"
    },
    "name": "Warehouse Freezer 001"
  },
  "entityClass": "warehouse_freezer",
  "entityId": "warehouse_freezer_001",
  "homeId": 5,
  "parentId": "warehouse_room_003",
  "projectId": 1,
  "timeZone": "Europe/Berlin",
  "updatedAt": "2021-09-02T22:19:39Z"
}

`401` Authorization is required to access this resource.

Content type: application/json

Property	Type	Required	Constraints	Description
`data`	object	No	read-only (server-generated)	Any relevant data related to error.
`reason`	string	Yes	read-only (server-generated)	Reason of error.

`403` Request failed because of invalid data or denied permission.

Content type: application/json

Property	Type	Required	Constraints	Description
`data`	object	No	read-only (server-generated)	Any relevant data related to error.
`reason`	string	Yes	read-only (server-generated)	Reason of error.

`429` Request failed because of rate limit.

Content type: application/json

Property	Type	Required	Constraints	Description
`data`	object	No	read-only (server-generated)	Any relevant data related to error.
`reason`	string	Yes	read-only (server-generated)	Reason of error.

`500` An unexpected error has occurred.

Content type: application/json

Property	Type	Required	Constraints	Description
`data`	object	No	read-only (server-generated)	Any relevant data related to error.
`reason`	string	Yes	read-only (server-generated)	Reason of error.

`503` The service is temporarily unavailable.

Content type: application/json

Property	Type	Required	Constraints	Description
`data`	object	No	read-only (server-generated)	Any relevant data related to error.
`reason`	string	Yes	read-only (server-generated)	Reason of error.

Create entity instance

Authentication

Path parameters

Request body

Responses

201 Successful creation of entity instance.

Response example

401 Authorization is required to access this resource.

403 Request failed because of invalid data or denied permission.

429 Request failed because of rate limit.

500 An unexpected error has occurred.

503 The service is temporarily unavailable.

`201` Successful creation of entity instance.

`401` Authorization is required to access this resource.

`403` Request failed because of invalid data or denied permission.

`429` Request failed because of rate limit.

`500` An unexpected error has occurred.

`503` The service is temporarily unavailable.