Entities

Entities

@toothfairyai/sdk@latest…

Entity Management Module Handles entity CRUD operations (topics, intents, NER entities).

Accessed via client.entities.

Methods

Method	HTTP	Endpoint
create	POST	POST /entity/create
get	GET	GET /entity/get/{id}
update	POST	POST /entity/update
delete	DELETE	DELETE /entity/delete/{id}
list	GET	GET /entity/list
getByType	—	derived
search	—	derived

create

Create a new entity

async create(
    label: string,
    entityType: EntityType = 'topic',
    options: {
      description?: string;
      emoji?: string;
      parentEntity?: string;
      backgroundColor?: string;
    } = {}
)

Endpoint: POST /entity/create · API service

Request fields

Field	Type	Required	Description
id	string	no	Unique identifier
workspaceid	string	yes	Unique workspace identifier (UUID v4)
label	string	yes	Human-readable display name
type	string	no	Type classification (free-form string identifier)

Allowed: ner, intent, topic | | description | string | no | Detailed description of purpose and capabilities | | emoji | string | no | Emoji icon for the folder | | parentEntity | string | no | ID of the parent entity (for nesting) | | backgroundColor | string | no | Hex color code for the entity's background | | owner | string | no | Owner of this resource | | createdBy | string | no | ID of the user who created this resource | | updatedBy | string | no | ID of the user who last updated this resource |

Response fields

Field	Type	Description
id	string	Unique identifier for the entity
owner	string	Owner of this resource
label	string	Human-readable name of the entity
type	string	Classification type of the entity

Allowed: ner, intent, topic, agentGroup, functionGroup, hookGroup | | description | string | Detailed description of the entity's purpose | | emoji | string | Emoji character representing the entity | | parentEntity | string | ID of parent entity for hierarchical organization | | backgroundColor | string | Background color as hex value for UI display | | workspaceID | string | Unique workspace identifier (UUID v4) | | createdBy | string | User ID who created the entity | | updatedBy | string | User ID who last updated the entity | | createdAt | string | Timestamp when this resource was created | | updatedAt | string | Timestamp when this resource was last updated |

Example

const result = await client.entities.create('…');

get

Get an entity by ID

async get(entityId: string)

Endpoint: GET /entity/get/{id} · API service

Response

Returns the EntityAI object — fields documented in the create section above.

Example

const result = await client.entities.get('agent-id');

update

Update an existing entity

async update(
    entityId: string,
    options: {
      label?: string;
      description?: string;
      emoji?: string;
      parentEntity?: string;
      backgroundColor?: string;
    } = {}
)

Endpoint: POST /entity/update · API service

Request fields

Field	Type	Required	Description
id	string	yes	Unique identifier
workspaceid	string	no	Unique workspace identifier (UUID v4)
label	string	no	Human-readable display name
type	string	no	Type classification (free-form string identifier)

Allowed: ner, intent, topic | | description | string | no | Detailed description of purpose and capabilities | | emoji | string | no | Emoji icon for the folder | | parentEntity | string | no | ID of the parent entity (for nesting) | | backgroundColor | string | no | Hex color code for the entity's background | | owner | string | no | Owner of this resource | | createdBy | string | no | ID of the user who created this resource | | updatedBy | string | no | ID of the user who last updated this resource |

Response

Returns the EntityAI object — fields documented in the create section above.

Example

const result = await client.entities.update('agent-id');

delete

Delete an entity

async delete(entityId: string): Promise<

Endpoint: DELETE /entity/delete/{id} · API service

Response fields

Field	Type	Description
success	boolean	Operation success status
data	object	Response data
message	string	Optional success message

Example

const result = await client.entities.delete('agent-id');

list

List entities in the workspace

async list(limit?: number, entityType?: EntityType)

Endpoint: GET /entity/list · API service

Example

const result = await client.entities.list();

getByType

Get entities by type

async getByType(entityType: EntityType, limit?: number)

Derived method — delegates to another SDK call and performs no direct HTTP request.

Example

const result = await client.entities.getByType(…);

search

Search entities by label

async search(searchTerm: string, entityType?: EntityType)

Derived method — delegates to another SDK call and performs no direct HTTP request.

Example

const result = await client.entities.search('…');