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

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 · int32Required

Current page, starting at 1

Default: 1

sizeinteger · int32Required

Size of the page

Default: 5

orderBystringOptional

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

Default: updatedAt

directionstringOptional

Order direction(ASC/DESC), defaulted to DESC

Default: DESC

maskingFilterstring · enumOptional

Used to filter masked entities, defaulted to ALL

Default: ALLPossible values:

searchTermstringOptional

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

Responses

200

Ok

application/json

400

Bad Request

*/*

401

Unauthorized

*/*

403

Forbidden

*/*

404

Not Found

*/*

409

Conflict

*/*

422

Unprocessable Entity

*/*

500

Internal Server Error

*/*

get

HTTPcURLJavaScriptPython

GET /org/{orgUUID}/env/{envUUID}/bot/{botUUID}/entities?page=1&size=1 HTTP/1.1
Host: 
Accept: */*

{
  "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,
  "content": [
    {
      "flows": [
        {
          "flowId": "text",
          "flowName": "text"
        }
      ],
      "entity": {
        "id": "text",
        "name": "text",
        "description": "text",
        "isMasked": true,
        "updatedAt": "2025-05-09T11:20:07.662Z",
        "updatedBy": "text",
        "user": {
          "uuid": "text",
          "name": "text",
          "imageUrl": "text"
        },
        "entityValues": [
          {
            "type": "text"
          }
        ],
        "tags": [
          {
            "uuid": "text",
            "name": "text",
            "objectRef": "text",
            "tagTypeId": 1
          }
        ]
      }
    }
  ],
  "number": 1,
  "sort": {
    "unsorted": true,
    "sorted": true,
    "empty": true
  },
  "first": true,
  "last": true,
  "empty": true
}

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

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 · int32Optional

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

Default: 6

Responses

200

Ok

application/json

Responsestring[]

400

Bad Request

*/*

401

Unauthorized

*/*

403

Forbidden

*/*

404

Not Found

*/*

409

Conflict

*/*

422

Unprocessable Entity

*/*

500

Internal Server Error

*/*

get

HTTPcURLJavaScriptPython

GET /org/{orgUUID}/env/{envUUID}/bot/{botUUID}/entities/quicksearch?searchTerm=text HTTP/1.1
Host: 
Accept: */*

[
  "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

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

200

Ok

application/json

400

Bad Request

*/*

401

Unauthorized

*/*

403

Forbidden

*/*

404

Not Found

*/*

409

Conflict

*/*

422

Unprocessable Entity

*/*

500

Internal Server Error

application/json

get

HTTPcURLJavaScriptPython

GET /org/{orgUUID}/env/{envUUID}/bot/{botUUID}/entities/list-on-flow HTTP/1.1
Host: 
Accept: */*

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

CRUD Operations

Creates a brand new entity

post

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

Structure used both to request the creation of a new entity and to request an update

namestringRequired

Name of the entity being created.

descriptionstringOptional

Description of the entity.

typestringRequired

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

cellEnablebooleanOptional

Whether or not this entity is enabled for cells.

maskedbooleanOptional

Responses

200

Ok

application/json

400

Bad Request

*/*

401

Unauthorized

*/*

403

Forbidden

*/*

404

Not Found

*/*

409

Conflict

*/*

422

Unprocessable Entity

*/*

500

Internal Server Error

*/*

post

HTTPcURLJavaScriptPython

POST /org/{orgUUID}/env/{envUUID}/bot/{botUUID}/entities HTTP/1.1
Host: 
Content-Type: application/json
Accept: */*
Content-Length: 237

{
  "name": "text",
  "description": "text",
  "type": "text",
  "tags": [
    {
      "id": "text",
      "name": "text"
    }
  ],
  "entityValue": [
    {
      "id": "text",
      "value": "text",
      "type": "text",
      "samples": [
        "text"
      ],
      "synonyms": [
        "text"
      ],
      "patterns": [
        "text"
      ]
    }
  ],
  "cellEnable": true,
  "masked": true
}

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

Retrieves info from a specific given entity.

get

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

200

Ok

application/json

400

Bad Request

*/*

401

Unauthorized

*/*

403

Forbidden

*/*

404

Resource not found

*/*

409

Conflict

*/*

422

Unprocessable Entity

*/*

500

Internal Server Error

*/*

get

HTTPcURLJavaScriptPython

GET /org/{orgUUID}/env/{envUUID}/bot/{botUUID}/entities/{uuid} HTTP/1.1
Host: 
Accept: */*

{
  "entity": {
    "id": "text",
    "name": "text",
    "description": "text",
    "isMasked": true,
    "updatedAt": "2025-05-09T11:20:07.662Z",
    "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"
    }
  ]
}

Updates an existing entity according to sent DTO.

put

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

Structure used both to request the creation of a new entity and to request an update

namestringRequired

Name of the entity being created.

descriptionstringOptional

Description of the entity.

typestringRequired

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

cellEnablebooleanOptional

Whether or not this entity is enabled for cells.

maskedbooleanOptional

Responses

200

Ok

application/json

400

Bad Request

*/*

401

Unauthorized

*/*

403

Forbidden

*/*

404

Not Found

*/*

409

Conflict

*/*

422

Unprocessable Entity

*/*

500

Internal Server Error

*/*

put

HTTPcURLJavaScriptPython

PUT /org/{orgUUID}/env/{envUUID}/bot/{botUUID}/entities/{uuid} HTTP/1.1
Host: 
Content-Type: application/json
Accept: */*
Content-Length: 237

{
  "name": "text",
  "description": "text",
  "type": "text",
  "tags": [
    {
      "id": "text",
      "name": "text"
    }
  ],
  "entityValue": [
    {
      "id": "text",
      "value": "text",
      "type": "text",
      "samples": [
        "text"
      ],
      "synonyms": [
        "text"
      ],
      "patterns": [
        "text"
      ]
    }
  ],
  "cellEnable": true,
  "masked": true
}

{
  "entity": {
    "id": "text",
    "name": "text",
    "description": "text",
    "isMasked": true,
    "updatedAt": "2025-05-09T11:20:07.662Z",
    "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"
    }
  ]
}

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

delete

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

200

Ok

400

Bad Request

*/*

401

Unauthorized

*/*

403

Forbidden

*/*

404

Not Found

*/*

409

Conflict

*/*

422

Unprocessable Entity

*/*

500

Internal Server Error

*/*

delete

HTTPcURLJavaScriptPython

DELETE /org/{orgUUID}/env/{envUUID}/bot/{botUUID}/entities/{uuid} HTTP/1.1
Host: 
Accept: */*

No content

Auxiliary Methods

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

post

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

Structure used to infer whether a Synonym is available to a bot or not.

synonymstringRequired

Name of the Synonym. Capitalization does not matter.

Responses

200

Ok

400

Bad Request

*/*

401

Unauthorized

*/*

403

Forbidden

*/*

404

Not Found

*/*

409

Term not available

*/*

422

Unprocessable Entity

*/*

500

Internal Server Error

*/*

post

HTTPcURLJavaScriptPython

POST /org/{orgUUID}/env/{envUUID}/bot/{botUUID}/entities/synonyms HTTP/1.1
Host: 
Content-Type: application/json
Accept: */*
Content-Length: 18

{
  "synonym": "text"
}

No content

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

post

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

Structure used to infer whether a Pattern is available to a bot or not.

patternstringRequired

Name of the Pattern. Capitalization matters.

Responses

200

Ok

400

Bad Request

*/*

401

Unauthorized

*/*

403

Forbidden

*/*

404

Not Found

*/*

409

Term not available

*/*

422

Unprocessable Entity

*/*

500

Internal Server Error

*/*

post

HTTPcURLJavaScriptPython

POST /org/{orgUUID}/env/{envUUID}/bot/{botUUID}/entities/patterns HTTP/1.1
Host: 
Content-Type: application/json
Accept: */*
Content-Length: 18

{
  "pattern": "text"
}

No content

System Entities

Pagination and Listings

Fetches a list of all System Entities and their status.

get

Path parameters

orgUUIDstringRequired

A valid uuid of organization

envUUIDstringRequired

A valid uuid of environment

botUUIDstringRequired

A valid uuid of bot

Query parameters

pageinteger · int32Required

Current page, starting at 1

Default: 1

sizeinteger · int32Required

Size of the page

Default: 5

Responses

200

Ok

application/json

400

Bad Request

*/*

401

Unauthorized

*/*

403

Forbidden

*/*

404

Not Found

*/*

409

Conflict

*/*

422

Unprocessable Entity

*/*

500

Internal Server Error

*/*

get

HTTPcURLJavaScriptPython

GET /org/{orgUUID}/env/{envUUID}/bot/{botUUID}/system-entities?page=1&size=1 HTTP/1.1
Host: 
Accept: */*

{
  "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,
  "content": [
    {
      "id": 1,
      "name": "text",
      "enabled": true
    }
  ],
  "number": 1,
  "sort": {
    "unsorted": true,
    "sorted": true,
    "empty": true
  },
  "first": true,
  "last": true,
  "empty": true
}

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

Path parameters

orgUUIDstringRequired

A valid uuid of organization

envUUIDstringRequired

A valid uuid of environment

botUUIDstringRequired

A valid uuid of bot

idinteger · int64Required

Responses

200

Ok

application/json

400

Bad Request

*/*

401

Unauthorized

*/*

403

Forbidden

*/*

404

Not Found

*/*

409

Conflict

*/*

422

Unprocessable Entity

*/*

500

Internal Server Error

*/*

get

HTTPcURLJavaScriptPython

GET /org/{orgUUID}/env/{envUUID}/bot/{botUUID}/system-entities/{id} HTTP/1.1
Host: 
Accept: */*

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

Updates one of a bot's system Entities.

put

Path parameters

orgUUIDstringRequired

A valid uuid of organization

envUUIDstringRequired

A valid uuid of environment

botUUIDstringRequired

A valid uuid of bot

idinteger · int64Required

Body

The structure for the update

enabledbooleanOptional

Wether you are enabling or disabling the system entity.

Responses

200

Ok

application/json

400

Bad Request

*/*

401

Unauthorized

*/*

403

Forbidden

*/*

404

Not Found

*/*

409

Conflict

*/*

422

Unprocessable Entity

*/*

500

Internal Server Error

*/*

put

HTTPcURLJavaScriptPython

PUT /org/{orgUUID}/env/{envUUID}/bot/{botUUID}/system-entities/{id} HTTP/1.1
Host: 
Content-Type: application/json
Accept: */*
Content-Length: 16

{
  "enabled": true
}

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