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

orgUUIDstringrequired

A valid uuid of an organization

envUUIDstringrequired

A valid uuid of an environment

botUUIDstringrequired

The UUID of the bot whose entities you are searching

Query parameters

pageinteger · int32 · default: 1required

Current page, starting at 1

sizeinteger · int32 · default: 5required

Size of the page

orderBystring · default: updatedAt

Criteria to order result, defaulted to updatedAt date. Possible fields include name, createdAt, updatedAt, createdBy and updatedBy.

directionstring · default: DESC

Order direction(ASC/DESC), defaulted to DESC

maskingFilterstring · enum · default: ALL

Used to filter masked entities, defaulted to ALL

Options: ALL, MASKED, UNMASKED

searchTermstring

Term being searched. This expects one optional String matching the name of an entity.

Responses

application/json

*/*

*/*

*/*

*/*

*/*

*/*

*/*

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url '/org/{orgUUID}/env/{envUUID}/bot/{botUUID}/entities?page=1&size=5'

200

400

401

403

404

409

422

500

200

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

Ok

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

orgUUIDstringrequired

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

envUUIDstringrequired

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

botUUIDstringrequired

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

Query parameters

searchTermstringrequired

Term being searched

limitinteger · int32 · default: 6

How many items will be returned in the list. Defaults to 6.

Responses

application/json

*/*

*/*

*/*

*/*

*/*

*/*

*/*

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url '/org/{orgUUID}/env/{envUUID}/bot/{botUUID}/entities/quicksearch?searchTerm=text'

200

400

401

403

404

409

422

500

200

[
  "text"
]

Ok

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

orgUUIDstringrequired

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

envUUIDstringrequired

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

botUUIDstringrequired

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

Responses

application/json

*/*

*/*

*/*

*/*

*/*

*/*

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url '/org/{orgUUID}/env/{envUUID}/bot/{botUUID}/entities/list-on-flow'

200

400

401

403

404

409

422

500

200

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

Ok

CRUD Operations

Creates a brand new entity

post

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

Path parameters

orgUUIDstringrequired

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

envUUIDstringrequired

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

botUUIDstringrequired

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

Body

namestringrequired

Name of the entity being created.

descriptionstring

Description of the entity.

typestringrequired

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

cellEnableboolean

Whether or not this entity is enabled for cells.

maskedboolean

tagsobject[]required

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

entityValueobject[]

A list of values for your entity.

Responses

application/json

*/*

*/*

*/*

*/*

*/*

*/*

*/*

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request POST \
  --url '/org/{orgUUID}/env/{envUUID}/bot/{botUUID}/entities' \
  --header 'Content-Type: application/json' \
  --data '{"name":"text","type":"text","tags":[{}],"entityValue":[{"value":"text","type":"text","samples":[null],"synonyms":[null],"patterns":[null]}]}'

200

400

401

403

404

409

422

500

200

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

Ok

Retrieves info from a specific given entity.

get

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

Path parameters

orgUUIDstringrequired

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

envUUIDstringrequired

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

botUUIDstringrequired

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

uuidstringrequired

The entity's uuid

Responses

application/json

*/*

*/*

*/*

*/*

*/*

*/*

*/*

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url '/org/{orgUUID}/env/{envUUID}/bot/{botUUID}/entities/{uuid}'

200

400

401

403

404

409

422

500

200

{
  "entity": {
    "id": "text",
    "name": "text",
    "description": "text",
    "isMasked": true,
    "updatedAt": "2025-02-21T18:14:11.002Z",
    "updatedBy": "text",
    "user": {
      "uuid": "text",
      "name": "text",
      "imageUrl": "text"
    },
    "tags": [
      {
        "uuid": "text",
        "name": "text",
        "objectRef": "text",
        "tagTypeId": 1
      }
    ]
  },
  "entityValue": [
    {
      "id": "text",
      "type": "text",
      "value": "text",
      "synonyms": [
        "text"
      ],
      "patterns": [
        "text"
      ]
    }
  ],
  "flows": [
    {
      "flowId": "text",
      "flowName": "text"
    }
  ]
}

Ok

Updates an existing entity according to sent DTO.

put

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

Path parameters

orgUUIDstringrequired

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

envUUIDstringrequired

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

botUUIDstringrequired

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

uuidstringrequired

The entity's uuid

Body

namestringrequired

Name of the entity being created.

descriptionstring

Description of the entity.

typestringrequired

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

cellEnableboolean

Whether or not this entity is enabled for cells.

maskedboolean

tagsobject[]required

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

entityValueobject[]

A list of values for your entity.

Responses

application/json

*/*

*/*

*/*

*/*

*/*

*/*

*/*

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request PUT \
  --url '/org/{orgUUID}/env/{envUUID}/bot/{botUUID}/entities/{uuid}' \
  --header 'Content-Type: application/json' \
  --data '{"name":"text","type":"text","tags":[{}],"entityValue":[{"value":"text","type":"text","samples":[null],"synonyms":[null],"patterns":[null]}]}'

200

400

401

403

404

409

422

500

200

{
  "entity": {
    "id": "text",
    "name": "text",
    "description": "text",
    "isMasked": true,
    "updatedAt": "2025-02-21T18:14:11.002Z",
    "updatedBy": "text",
    "user": {
      "uuid": "text",
      "name": "text",
      "imageUrl": "text"
    },
    "tags": [
      {
        "uuid": "text",
        "name": "text",
        "objectRef": "text",
        "tagTypeId": 1
      }
    ]
  },
  "entityValue": [
    {
      "id": "text",
      "type": "text",
      "value": "text",
      "synonyms": [
        "text"
      ],
      "patterns": [
        "text"
      ]
    }
  ],
  "flows": [
    {
      "flowId": "text",
      "flowName": "text"
    }
  ]
}

Ok

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

orgUUIDstringrequired

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

envUUIDstringrequired

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

botUUIDstringrequired

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

uuidstringrequired

The entity's uuid

Responses

*/*

*/*

*/*

*/*

*/*

*/*

*/*

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request DELETE \
  --url '/org/{orgUUID}/env/{envUUID}/bot/{botUUID}/entities/{uuid}'

200

400

401

403

404

409

422

500

200

No body

Ok

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

orgUUIDstringrequired

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

envUUIDstringrequired

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

botUUIDstringrequired

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

Body

synonymstringrequired

Name of the Synonym. Capitalization does not matter.

Responses

*/*

*/*

*/*

*/*

*/*

*/*

*/*

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request POST \
  --url '/org/{orgUUID}/env/{envUUID}/bot/{botUUID}/entities/synonyms' \
  --header 'Content-Type: application/json' \
  --data '{"synonym":"text"}'

200

400

401

403

404

409

422

500

200

No body

Ok

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

orgUUIDstringrequired

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

envUUIDstringrequired

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

botUUIDstringrequired

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

Body

patternstringrequired

Name of the Pattern. Capitalization matters.

Responses

*/*

*/*

*/*

*/*

*/*

*/*

*/*

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request POST \
  --url '/org/{orgUUID}/env/{envUUID}/bot/{botUUID}/entities/patterns' \
  --header 'Content-Type: application/json' \
  --data '{"pattern":"text"}'

200

400

401

403

404

409

422

500

200

No body

Ok

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

orgUUIDstringrequired

A valid uuid of organization

envUUIDstringrequired

A valid uuid of environment

botUUIDstringrequired

A valid uuid of bot

Query parameters

pageinteger · int32 · default: 1required

Current page, starting at 1

sizeinteger · int32 · default: 5required

Size of the page

Responses

application/json

*/*

*/*

*/*

*/*

*/*

*/*

*/*

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url '/org/{orgUUID}/env/{envUUID}/bot/{botUUID}/system-entities?page=1&size=5'

200

400

401

403

404

409

422

500

200

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

Ok

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

orgUUIDstringrequired

A valid uuid of organization

envUUIDstringrequired

A valid uuid of environment

botUUIDstringrequired

A valid uuid of bot

idinteger · int64required

Responses

application/json

*/*

*/*

*/*

*/*

*/*

*/*

*/*

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url '/org/{orgUUID}/env/{envUUID}/bot/{botUUID}/system-entities/{id}'

200

400

401

403

404

409

422

500

200

{
  "systemEntity": {
    "id": 1,
    "name": "text",
    "enabled": true
  },
  "flows": [
    {
      "uuid": "text",
      "name": "text"
    }
  ]
}

Ok

Updates one of a bot's system Entities.

put

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

Path parameters

orgUUIDstringrequired

A valid uuid of organization

envUUIDstringrequired

A valid uuid of environment

botUUIDstringrequired

A valid uuid of bot

idinteger · int64required

Body

enabledboolean

Wether you are enabling or disabling the system entity.

Responses

application/json

*/*

*/*

*/*

*/*

*/*

*/*

*/*

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request PUT \
  --url '/org/{orgUUID}/env/{envUUID}/bot/{botUUID}/system-entities/{id}' \
  --header 'Content-Type: application/json'

200

400

401

403

404

409

422

500

200

{
  "systemEntity": {
    "id": 1,
    "name": "text",
    "enabled": true
  },
  "flows": [
    {
      "uuid": "text",
      "name": "text"
    }
  ]
}

Ok