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
searchTermstringOptional

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

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
Responses
200
Ok
application/json
get
GET /org/{orgUUID}/env/{envUUID}/bot/{botUUID}/entities?page=1&size=5 HTTP/1.1
Host: 
Accept: */*
{
  "totalPages": 1,
  "totalElements": 1,
  "first": true,
  "last": true,
  "pageable": {
    "paged": true,
    "unpaged": true,
    "pageNumber": 1,
    "pageSize": 1,
    "sort": {
      "unsorted": true,
      "sorted": true,
      "empty": true
    },
    "offset": 1
  },
  "numberOfElements": 1,
  "sort": {
    "unsorted": true,
    "sorted": true,
    "empty": true
  },
  "size": 1,
  "content": [
    {
      "flows": [
        {
          "flowId": "text",
          "flowName": "text"
        }
      ],
      "entity": {
        "id": "text",
        "name": "text",
        "updatedAt": "2025-07-01T01:40:16.842Z",
        "updatedBy": "text",
        "user": {
          "uuid": "text",
          "name": "text",
          "imageUrl": "text"
        },
        "entityValues": [
          {
            "type": "text"
          }
        ],
        "tags": [
          {
            "uuid": "text",
            "name": "text",
            "objectRef": "text",
            "tagTypeId": 1
          }
        ]
      }
    }
  ],
  "number": 1,
  "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

A valid organization Uuid

envUUIDstringRequired

A valid environment Uuid

botUUIDstringRequired

A valid bot uuid to search

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[]
get
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

A valid organization Uuid

envUUIDstringRequired

A valid environment Uuid

botUUIDstringRequired

A valid bot Uuid

Responses
200
Ok
application/json
get
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"
        }
      ]
    }
  ],
  "systemEntities": [
    {
      "id": 1,
      "name": "text",
      "enabled": true
    }
  ]
}

CRUD Operations

Creates a brand new entity

post
Path parameters
orgUUIDstringRequired

A valid uuid of organization

envUUIDstringRequired

A valid uuid of environment

botUUIDstringRequired

A valid uuid of bot

Body

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

namestringRequired

Name of the entity being created.

typestringRequired

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

cellEnablebooleanOptional

Wether or not this entity is enabled for cells.

Responses
200
Ok
application/json
post
POST /org/{orgUUID}/env/{envUUID}/bot/{botUUID}/entities HTTP/1.1
Host: 
Content-Type: application/json
Accept: */*
Content-Length: 202

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

Updates an existing Entity according to sent DTO.

put
Path parameters
orgUUIDstringRequired

A valid uuid of organization

envUUIDstringRequired

A valid uuid of environment

botUUIDstringRequired

A valid uuid of bot

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.

typestringRequired

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

cellEnablebooleanOptional

Wether or not this entity is enabled for cells.

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

{
  "name": "text",
  "type": "text",
  "tags": [
    {
      "id": "text",
      "name": "text"
    }
  ],
  "entityValue": [
    {
      "id": "text",
      "value": "text",
      "type": "text",
      "samples": [
        "text"
      ],
      "synonyms": [
        "text"
      ],
      "patterns": [
        "text"
      ]
    }
  ],
  "cellEnable": true
}
{
  "entity": {
    "id": "text",
    "name": "text",
    "updatedAt": "2025-07-01T01:40:16.842Z",
    "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

A valid uuid of organization

envUUIDstringRequired

A valid uuid of environment

botUUIDstringRequired

A valid uuid of bot

uuidstringRequired

The entity's uuid

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

No content

Auxiliary Methods

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

post
Path parameters
orgUUIDstringRequired

A valid uuid of organization

envUUIDstringRequired

A valid uuid of environment

botUUIDstringRequired

A valid uuid of bot

Body

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

synonymstringRequired

Name of the Synonym. Capitalization does not matter.

Responses
200
Ok
post
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 existance of a pattern. Retuns 200 if term is available, and 409 otherwise.

post
Path parameters
orgUUIDstringRequired

A valid uuid of organization

envUUIDstringRequired

A valid uuid of environment

botUUIDstringRequired

A valid uuid of bot

Body

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

patternstringRequired

Name of the Pattern. Capitalization matters.

Responses
200
Ok
post
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
get
GET /org/{orgUUID}/env/{envUUID}/bot/{botUUID}/system-entities?page=1&size=5 HTTP/1.1
Host: 
Accept: */*
{
  "totalPages": 1,
  "totalElements": 1,
  "first": true,
  "last": true,
  "pageable": {
    "paged": true,
    "unpaged": true,
    "pageNumber": 1,
    "pageSize": 1,
    "sort": {
      "unsorted": true,
      "sorted": true,
      "empty": true
    },
    "offset": 1
  },
  "numberOfElements": 1,
  "sort": {
    "unsorted": true,
    "sorted": true,
    "empty": true
  },
  "size": 1,
  "content": [
    {
      "id": 1,
      "name": "text",
      "enabled": true
    }
  ],
  "number": 1,
  "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
get
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
put
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"
    }
  ]
}

Was this helpful?

#144: 4.5 - Gen AI (KAI, Rephrase, Assist) + What's New (Notifications)

Change request updated