Folders

Folders

toothfairyai@latest…

Manager for folder operations.

This manager provides methods to create, update, and manage folders including hierarchical operations.

Example:

>>> client = ToothFairyClient(api_key="...", workspace_id="...")
>>> folder = client.folders.create(
...     name="Documents"
... )

Accessed via client.folders.

Methods

Method	HTTP	Endpoint
create	POST	POST /folder/create
get	GET	GET /folder/get/{folder_id}
update	POST	POST /folder/update
delete	DELETE	DELETE /folder/delete/{folder_id}
list	GET	GET /folder/list
get_root_folders	—	derived
get_subfolders	—	derived
get_tree	—	derived
search	—	derived

create

Create a new folder.

def create(
    name: str,
    description: Optional[str] = None,
    emoji: Optional[str] = None,
    status: str = 'active',
    parent: Optional[str] = None,
    allowed_topics: Optional[List[str]] = None
) -> Folder

Endpoint: POST /folder/create · API service

Request fields

Python kwarg	Wire field	Type	Required	Description
id	id	string	no	Unique identifier
workspace_id	workspaceid	string	yes	Unique workspace identifier (UUID v4)
name	name	string	yes	Name of the resource
description	description	string	no	Detailed description of purpose and capabilities
emoji	emoji	string	no	Emoji icon for the folder
status	status	string	no	Current status of the resource

Allowed: active, inactive | | parent | parent | string | no | ID of the parent folder (for nesting) | | allowed_topics | allowedTopics | string | no | List of topic IDs the agent is restricted to (max 10) | | owner | owner | string | no | Owner of this resource | | created_by | createdBy | string | no | ID of the user who created this resource | | updated_by | updatedBy | string | no | ID of the user who last updated this resource |

Always pass snake_case keyword arguments — the Python kwarg column shows the exact name to use for each wire field (as a named parameter where it appears in the method signature, otherwise via **kwargs). The SDK converts it deterministically to the camelCase wire key the API expects. Passing camelCase directly is deprecated: it emits a warning and converts to the same wire key.

Response fields

Field	Type	Description
id	string	Unique identifier for the folder
owner	string	Owner of the folder
name	string	Name of the folder
description	string	Description of the folder
emoji	string	Emoji character representing the folder
status	string	Status of the folder

Allowed: active, inactive | | allowedTopics | object | List of topic IDs the agent is restricted to (max 10) | | parent | string | Parent folder ID for nested folder structure | | workspaceID | string | Unique workspace identifier (UUID v4) | | createdBy | string | User ID who created the folder | | updatedBy | string | User ID who last updated the folder | | createdAt | string | Timestamp when this resource was created | | updatedAt | string | Timestamp when this resource was last updated |

Example

client.folders.create(name="…")

get

Get a folder by ID.

def get(folder_id: str) -> Folder

Endpoint: GET /folder/get/{folder_id} · API service

Response

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

Example

client.folders.get(folder_id="agent-id")

update

Update a folder.

def update(
    folder_id: str,
    name: Optional[str] = None,
    description: Optional[str] = None,
    emoji: Optional[str] = None,
    status: Optional[str] = None,
    parent: Optional[str] = None,
    allowed_topics: Optional[List[str]] = None
) -> Folder

Endpoint: POST /folder/update · API service

Request fields

Python kwarg	Wire field	Type	Required	Description
id	id	string	yes	Unique identifier
workspace_id	workspaceid	string	no	Unique workspace identifier (UUID v4)
name	name	string	no	Name of the resource
description	description	string	no	Detailed description of purpose and capabilities
emoji	emoji	string	no	Emoji icon for the folder
status	status	string	no	Current status of the resource

Allowed: active, inactive | | parent | parent | string | no | ID of the parent folder (for nesting) | | allowed_topics | allowedTopics | string | no | List of topic IDs the agent is restricted to (max 10) | | owner | owner | string | no | Owner of this resource | | created_by | createdBy | string | no | ID of the user who created this resource | | updated_by | updatedBy | string | no | ID of the user who last updated this resource |

Always pass snake_case keyword arguments — the Python kwarg column shows the exact name to use for each wire field (as a named parameter where it appears in the method signature, otherwise via **kwargs). The SDK converts it deterministically to the camelCase wire key the API expects. Passing camelCase directly is deprecated: it emits a warning and converts to the same wire key.

Response

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

Example

client.folders.update(folder_id="agent-id")

delete

Delete a folder.

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

Endpoint: DELETE /folder/delete/{folder_id} · API service

Response

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

Example

client.folders.delete(folder_id="agent-id")

list

List folders.

def list(
    status: Optional[str] = None,
    limit: Optional[int] = None,
    offset: Optional[int] = None
) -> ListResponse

Endpoint: GET /folder/list · API service

Response

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

Example

client.folders.list()

get_root_folders

Get all root folders (folders without a parent).

def get_root_folders() -> List[Folder]

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

Example

client.folders.get_root_folders()

get_subfolders

Get all subfolders of a parent folder.

def get_subfolders(parent_id: str) -> List[Folder]

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

Example

client.folders.get_subfolders(parent_id="agent-id")

get_tree

Get the folder hierarchy as a tree structure.

def get_tree() -> List[FolderTreeNode]

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

Example

client.folders.get_tree()

search

Search folders by name.

def search(search_term: str) -> List[Folder]

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

Example

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