Entities

Entities

toothfairyai@latest…

Manager for entity operations.

This manager provides methods to create, update, and manage entities (topics, intents, and NER).

Example:

>>> client = ToothFairyClient(api_key="...", workspace_id="...")
>>> entity = client.entities.create(
...     label="Dental Cleaning",
...     entity_type="topic"
... )

Accessed via client.entities.

Methods

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

create

Create a new entity.

def create(
    label: str,
    entity_type: EntityType = 'topic',
    description: Optional[str] = None,
    emoji: Optional[str] = None,
    parent_entity: Optional[str] = None,
    background_color: Optional[str] = None
) -> Entity

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 |

The Python SDK accepts snake_case keyword arguments and converts them to the camelCase wire fields shown above.

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

client.entities.create(label="…")

get

Get an entity by ID.

def get(entity_id: str) -> Entity

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

Response

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

Example

client.entities.get(entity_id="agent-id")

update

Update an entity.

def update(
    entity_id: str,
    label: Optional[str] = None,
    description: Optional[str] = None,
    emoji: Optional[str] = None,
    parent_entity: Optional[str] = None,
    background_color: Optional[str] = None
) -> Entity

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 |

The Python SDK accepts snake_case keyword arguments and converts them to the camelCase wire fields shown above.

Response

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

Example

client.entities.update(entity_id="agent-id")

delete

Delete an entity.

def delete(entity_id: str) -> Dict[str, bool]

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

Response fields

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

Example

client.entities.delete(entity_id="agent-id")

list

List entities.

def list(
    limit: Optional[int] = None,
    entity_type: Optional[EntityType] = None
) -> ListResponse

Endpoint: GET /entity/list · API service

Example

client.entities.list()

get_by_type

Get entities by type.

def get_by_type(
    entity_type: EntityType,
    limit: Optional[int] = None
) -> List[Entity]

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

Example

client.entities.get_by_type(entity_type=…)

search

Search entities by label.

def search(
    search_term: str,
    entity_type: Optional[EntityType] = None
) -> List[Entity]

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

Example

client.entities.search(search_term="…")