Entity

The Entity API handle the CRUD operations for Entities, System Entities, and also an auxiliary method for the Dialog Manager.

API SUBPATH: eva-entity

Entities

Pagination and Listings

Searches and paginates through existing entities in a given bot.

GET/org/{orgUUID}/env/{envUUID}/bot/{botUUID}/entities

Path parameters

orgUUID*string

A valid uuid of an organization

envUUID*string

A valid uuid of an environment

botUUID*string

The UUID of the bot whose entities you are searching

Query parameters

Response

200400401403404409422500

Ok

Body

application/json

totalPagesinteger (int32)

totalElementsinteger (int64)

numberOfElementsinteger (int32)

pageablePageableObject (object)

sizeinteger (int32)

contentarray of EntityObject (object)

numberinteger (int32)

sortSortObject (object)

firstboolean

lastboolean

emptyboolean

Request

JavaScriptCurlPython

const response = await fetch('/org/{orgUUID}/env/{envUUID}/bot/{botUUID}/entities?page=1&size=5', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

200400401403404409422500

{
  "totalPages": 0,
  "totalElements": 0,
  "numberOfElements": 0,
  "pageable": {
    "unpaged": false,
    "paged": false,
    "pageNumber": 0,
    "pageSize": 0,
    "offset": 0,
    "sort": {
      "unsorted": false,
      "sorted": false,
      "empty": false
    }
  },
  "size": 0,
  "content": [
    {
      "flows": [
        {
          "flowId": "text",
          "flowName": "text"
        }
      ],
      "entity": {
        "id": "text",
        "name": "text",
        "description": "text",
        "isMasked": false,
        "updatedAt": "2024-12-21T12:02:08.590Z",
        "updatedBy": "text",
        "user": {
          "uuid": "text",
          "name": "text",
          "imageUrl": "text"
        },
        "entityValues": [
          {
            "type": "text"
          }
        ],
        "tags": [
          {
            "uuid": "text",
            "name": "text",
            "objectRef": "text",
            "tagTypeId": 0
          }
        ]
      }
    }
  ],
  "number": 0,
  "sort": {
    "unsorted": false,
    "sorted": false,
    "empty": false
  },
  "first": false,
  "last": false,
  "empty": false
}

Searches (greedily) for any entity names that exists in a bot, matching the typed term, left-to-right, and returns a list of up to 6 Strings, ordered alphabetically.

GET/org/{orgUUID}/env/{envUUID}/bot/{botUUID}/entities/quicksearch

Path parameters

orgUUID*string

It is the organization where the entities are, it is used to connect to the correct database

envUUID*string

It is the environment where the entities are, it is used to connect to the correct database

botUUID*string

It is the bot where the entities are, it is used to filter entities

Query parameters

Response

200400401403404409422500

Ok

Body

application/json

itemsstring

Request

JavaScriptCurlPython

const response = await fetch('/org/{orgUUID}/env/{envUUID}/bot/{botUUID}/entities/quicksearch?searchTerm=text', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

200400401403404409422500

[
  "text"
]

Return all bot entities not removed and all system entities enabled or not. Used inside the flow to choose one of them and create a entity cell

GET/org/{orgUUID}/env/{envUUID}/bot/{botUUID}/entities/list-on-flow

Path parameters

orgUUID*string

It is the organization where the entities are, it is used to connect to the correct database

envUUID*string

It is the environment where the entities are, it is used to connect to the correct database

botUUID*string

It is the bot where the entities are, it is used to filter entities

Response

200400401403404409422500

Ok

Body

application/json

entitiesarray of EntityDataListDTO (object)

List with entities

systemEntitiesarray of SystemEntityDTO (object)

List with system entities

Request

JavaScriptCurlPython

const response = await fetch('/org/{orgUUID}/env/{envUUID}/bot/{botUUID}/entities/list-on-flow', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

200400401403404409422500

{
  "entities": [
    {
      "id": "text",
      "name": "text",
      "tags": [
        "text"
      ],
      "entityValues": [
        {
          "id": "text",
          "value": "text",
          "type": "text",
          "samples": [
            "text"
          ]
        }
      ]
    }
  ],
  "systemEntities": [
    {
      "id": 0,
      "name": "text",
      "enabled": false
    }
  ]
}

CRUD Operations

Creates a brand new entity

POST/org/{orgUUID}/env/{envUUID}/bot/{botUUID}/entities

Path parameters

orgUUID*string

It is the organization where the entities are, it is used to connect to the correct database

envUUID*string

It is the environment where the entities are, it is used to connect to the correct database

botUUID*string

It is the bot where the entities are, it is used to filter entities

Body

application/json

name*string

Name of the entity being created.

descriptionstring

Description of the entity.

type*string

Type of the entity being created -- Expected values are either 'Synonym' or 'Pattern'. Anything else will be rejected.

tags*array of TagSimpleDTO (object)

A list of Tags to be created along with the entity, already assigning them.

entityValuearray of EntityCreationValueDTO (object)

A list of values for your entity.

cellEnableboolean

Whether or not this entity is enabled for cells.

maskedboolean

Response

200400401403404409422500

Ok

Body

application/json

statusstring

A status message informing the result

idstring

The UUID of the newly created entity

entityValuearray of EntityResponseDataValueDTO (object)

The entity values associated with the new entity

Request

JavaScriptCurlPython

const response = await fetch('/org/{orgUUID}/env/{envUUID}/bot/{botUUID}/entities', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "name": "text",
      "tags": [
        {}
      ],
      "type": "text"
    }),
});
const data = await response.json();

Response

200400401403404409422500

{
  "status": "text",
  "id": "text",
  "entityValue": [
    {
      "id": "text",
      "value": "text",
      "type": "text",
      "samples": [
        "text"
      ]
    }
  ]
}

Retrieves info from a specific given entity.

GET/org/{orgUUID}/env/{envUUID}/bot/{botUUID}/entities/{uuid}

Path parameters

orgUUID*string

It is the organization where the entities are, it is used to connect to the correct database

envUUID*string

It is the environment where the entities are, it is used to connect to the correct database

botUUID*string

It is the bot where the entities are, it is used to filter entities

uuid*string

The entity's uuid

Response

200400401403404409422500

Ok

Body

application/json

entityEntitySingleDTO (object)

entityValuearray of EntityValueSingleDTO (object)

flowsarray of FlowDTO (object)

Request

JavaScriptCurlPython

const response = await fetch('/org/{orgUUID}/env/{envUUID}/bot/{botUUID}/entities/{uuid}', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

200400401403404409422500

{
  "entity": {
    "id": "text",
    "name": "text",
    "description": "text",
    "isMasked": false,
    "updatedAt": "2024-12-21T12:02:08.590Z",
    "updatedBy": "text",
    "user": {
      "uuid": "text",
      "name": "text",
      "imageUrl": "text"
    },
    "tags": [
      {
        "uuid": "text",
        "name": "text",
        "objectRef": "text",
        "tagTypeId": 0
      }
    ]
  },
  "entityValue": [
    {
      "id": "text",
      "type": "text",
      "value": "text",
      "synonyms": [
        "text"
      ],
      "patterns": [
        "text"
      ]
    }
  ],
  "flows": [
    {
      "flowId": "text",
      "flowName": "text"
    }
  ]
}

Updates an existing entity according to sent DTO.

PUT/org/{orgUUID}/env/{envUUID}/bot/{botUUID}/entities/{uuid}

Path parameters

orgUUID*string

It is the organization where the entities are, it is used to connect to the correct database

envUUID*string

It is the environment where the entities are, it is used to connect to the correct database

botUUID*string

It is the bot where the entities are, it is used to filter entities

uuid*string

The entity's uuid

Body

application/json

name*string

Name of the entity being created.

descriptionstring

Description of the entity.

type*string

Type of the entity being created -- Expected values are either 'Synonym' or 'Pattern'. Anything else will be rejected.

tags*array of TagSimpleDTO (object)

A list of Tags to be created along with the entity, already assigning them.

entityValuearray of EntityCreationValueDTO (object)

A list of values for your entity.

cellEnableboolean

Whether or not this entity is enabled for cells.

maskedboolean

Response

200400401403404409422500

Ok

Body

application/json

entityEntitySingleDTO (object)

entityValuearray of EntityValueSingleDTO (object)

flowsarray of FlowDTO (object)

Request

JavaScriptCurlPython

const response = await fetch('/org/{orgUUID}/env/{envUUID}/bot/{botUUID}/entities/{uuid}', {
    method: 'PUT',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "name": "text",
      "tags": [
        {}
      ],
      "type": "text"
    }),
});
const data = await response.json();

Response

200400401403404409422500

{
  "entity": {
    "id": "text",
    "name": "text",
    "description": "text",
    "isMasked": false,
    "updatedAt": "2024-12-21T12:02:08.590Z",
    "updatedBy": "text",
    "user": {
      "uuid": "text",
      "name": "text",
      "imageUrl": "text"
    },
    "tags": [
      {
        "uuid": "text",
        "name": "text",
        "objectRef": "text",
        "tagTypeId": 0
      }
    ]
  },
  "entityValue": [
    {
      "id": "text",
      "type": "text",
      "value": "text",
      "synonyms": [
        "text"
      ],
      "patterns": [
        "text"
      ]
    }
  ],
  "flows": [
    {
      "flowId": "text",
      "flowName": "text"
    }
  ]
}

Deletes an entity. The entity is disabled rather than removed, but all of it's values and samples are permanently deleted.

DELETE/org/{orgUUID}/env/{envUUID}/bot/{botUUID}/entities/{uuid}

Path parameters

orgUUID*string

It is the organization where the entities are, it is used to connect to the correct database

envUUID*string

It is the environment where the entities are, it is used to connect to the correct database

botUUID*string

It is the bot where the entities are, it is used to filter entities

uuid*string

The entity's uuid

Response

200400401403404409422500

Ok

Request

JavaScriptCurlPython

const response = await fetch('/org/{orgUUID}/env/{envUUID}/bot/{botUUID}/entities/{uuid}', {
    method: 'DELETE',
    headers: {},
});
const data = await response.json();

Response

400401403404409422500

{
  "timestamp": 0,
  "errorCode": "text",
  "errorType": "API_ERROR",
  "message": "text",
  "path": "text"
}

Auxiliary Methods

Checks for the existence of a synonym. Returns 200 if term is available, and 400 otherwise.

POST/org/{orgUUID}/env/{envUUID}/bot/{botUUID}/entities/synonyms

Path parameters

orgUUID*string

It is the organization where the entities are, it is used to connect to the correct database

envUUID*string

It is the environment where the entities are, it is used to connect to the correct database

botUUID*string

It is the bot where the entities are, it is used to filter entities

Body

application/json

synonym*string

Name of the Synonym. Capitalization does not matter.

Response

200400401403404409422500

Ok

Request

JavaScriptCurlPython

const response = await fetch('/org/{orgUUID}/env/{envUUID}/bot/{botUUID}/entities/synonyms', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "synonym": "text"
    }),
});
const data = await response.json();

Response

400401403404409422500

{
  "timestamp": 0,
  "errorCode": "text",
  "errorType": "API_ERROR",
  "message": "text",
  "path": "text"
}

Checks for the existence of a pattern. Returns 200 if term is available, and 409 otherwise.

POST/org/{orgUUID}/env/{envUUID}/bot/{botUUID}/entities/patterns

Path parameters

orgUUID*string

It is the organization where the entities are, it is used to connect to the correct database

envUUID*string

It is the environment where the entities are, it is used to connect to the correct database

botUUID*string

It is the bot where the entities are, it is used to filter entities

Body

application/json

pattern*string

Name of the Pattern. Capitalization matters.

Response

200400401403404409422500

Ok

Request

JavaScriptCurlPython

const response = await fetch('/org/{orgUUID}/env/{envUUID}/bot/{botUUID}/entities/patterns', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "pattern": "text"
    }),
});
const data = await response.json();

Response

400401403404409422500

{
  "timestamp": 0,
  "errorCode": "text",
  "errorType": "API_ERROR",
  "message": "text",
  "path": "text"
}

System Entities

Pagination and Listings

Fetches a list of all System Entities and their status.

GET/org/{orgUUID}/env/{envUUID}/bot/{botUUID}/system-entities

Path parameters

orgUUID*string

A valid uuid of organization

envUUID*string

A valid uuid of environment

botUUID*string

A valid uuid of bot

Query parameters

Response

200400401403404409422500

Ok

Body

application/json

totalPagesinteger (int32)

totalElementsinteger (int64)

numberOfElementsinteger (int32)

pageablePageableObject (object)

sizeinteger (int32)

contentarray of EntitySystem (object)

numberinteger (int32)

sortSortObject (object)

firstboolean

lastboolean

emptyboolean

Request

JavaScriptCurlPython

const response = await fetch('/org/{orgUUID}/env/{envUUID}/bot/{botUUID}/system-entities?page=1&size=5', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

200400401403404409422500

{
  "totalPages": 0,
  "totalElements": 0,
  "numberOfElements": 0,
  "pageable": {
    "unpaged": false,
    "paged": false,
    "pageNumber": 0,
    "pageSize": 0,
    "offset": 0,
    "sort": {
      "unsorted": false,
      "sorted": false,
      "empty": false
    }
  },
  "size": 0,
  "content": [
    {
      "id": 0,
      "name": "text",
      "enabled": false
    }
  ],
  "number": 0,
  "sort": {
    "unsorted": false,
    "sorted": false,
    "empty": false
  },
  "first": false,
  "last": false,
  "empty": false
}

CRUD Operations

System entities are not created or deleted - They are instead a standard, default group of entities which are available for all Virtual Agents. Rather than creating them, you will enable or disable them.

Fetches a bot's System Entity and it's status.

GET/org/{orgUUID}/env/{envUUID}/bot/{botUUID}/system-entities/{id}

Path parameters

orgUUID*string

A valid uuid of organization

envUUID*string

A valid uuid of environment

botUUID*string

A valid uuid of bot

id*integer (int64)

Response

200400401403404409422500

Ok

Body

application/json

systemEntitySystemEntityDTO (object)

List with system entities

flowsarray of FlowResponseDTO (object)

A list of flows where this system entity is used.

Request

JavaScriptCurlPython

const response = await fetch('/org/{orgUUID}/env/{envUUID}/bot/{botUUID}/system-entities/{id}', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

200400401403404409422500

{
  "systemEntity": {
    "id": 0,
    "name": "text",
    "enabled": false
  },
  "flows": [
    {
      "uuid": "text",
      "name": "text"
    }
  ]
}

Updates one of a bot's system Entities.

PUT/org/{orgUUID}/env/{envUUID}/bot/{botUUID}/system-entities/{id}

Path parameters

orgUUID*string

A valid uuid of organization

envUUID*string

A valid uuid of environment

botUUID*string

A valid uuid of bot

id*integer (int64)

Body

application/json

enabledboolean

Wether you are enabling or disabling the system entity.

Response

200400401403404409422500

Ok

Body

application/json

systemEntitySystemEntityDTO (object)

List with system entities

flowsarray of FlowResponseDTO (object)

A list of flows where this system entity is used.

Request

JavaScriptCurlPython

const response = await fetch('/org/{orgUUID}/env/{envUUID}/bot/{botUUID}/system-entities/{id}', {
    method: 'PUT',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({}),
});
const data = await response.json();

Response

200400401403404409422500

{
  "systemEntity": {
    "id": 0,
    "name": "text",
    "enabled": false
  },
  "flows": [
    {
      "uuid": "text",
      "name": "text"
    }
  ]
}