Prompts

Prompts

toothfairyai@latest…

Manager for prompt operations.

This manager provides methods to create, update, and manage prompt templates.

Example:

>>> client = ToothFairyClient(api_key="...", workspace_id="...")
>>> prompt = client.prompts.create(
...     label="Greeting",
...     interpolation_string="Hello {{name}}! Welcome to our service."
... )

Accessed via client.prompts.

Methods

Method	HTTP	Endpoint
create	POST	POST /prompt/create
get	GET	GET /prompt/get/{prompt_id}
delete	DELETE	DELETE /prompt/delete/{prompt_id}
update	POST	POST /prompt/update
list	GET	GET /prompt/list
get_by_type	—	derived
get_by_agent	—	derived
get_by_scope	—	derived
search	—	derived
clone	—	derived

create

Create a new prompt.

def create(
    label: str,
    interpolation_string: str,
    prompt_type: str = 'custom',
    scope: Optional[str] = None,
    style: Optional[str] = None,
    domain: Optional[str] = None,
    prompt_placeholder: Optional[str] = None,
    available_to_agents: Optional[List[str]] = None
) -> Prompt

Endpoint: POST /prompt/create · API service

Request fields

Python kwarg	Wire field	Type	Required	Description
id	id	string	no	Unique identifier for the prompt
workspace_id	workspaceid	string	yes	Your workspace ID (UUID v4). Auto-injected by the SDK client from your configuration; you do not need to set it manually.
type	type	string	no	Prompt type classification
scope	scope	string	no	OAuth scope
style	style	string	no	Generation style: default, short, long, funny, informal, formal, interview, academic, business, creative, scientific, poetry, or news
domain	domain	string	no	Generation domain: editorial, customerService, sales, marketing, hr, finance, legal, medical, science, technology, or default
label	label	string	yes	Human-readable display name
prompt_length	promptLength	integer	yes	Length of the prompt in characters (32-2048)
prompt_placeholder	promptPlaceholder	string	no	Prompt placeholder text
interpolation_string	interpolationString	string	yes	Prompt interpolation string
available_to_agents	availableToAgents	string	no	List of agent IDs this prompt is available to
created_by	createdBy	string	no	User ID who created the prompt
updated_by	updatedBy	string	no	User ID who last updated the prompt

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 prompt
type	string	Prompt type classification
scope	string	OAuth scope
style	string	Generation style: default, short, long, funny, informal, formal, interview, academic, business, creative, scientific, poetry, or news
domain	string	Generation domain: editorial, customerService, sales, marketing, hr, finance, legal, medical, science, technology, or default
label	string	Human-readable display name
promptLength	number	Length of the prompt in characters (32-2048)
promptPlaceholder	string	Prompt placeholder text
interpolationString	string	Prompt interpolation string
availableToAgents	array<string>	List of agent IDs this prompt is available to
workspaceID	string	Unique workspace identifier (UUID v4)
createdBy	string	User ID who created the prompt
updatedBy	string	User ID who last updated the prompt
createdAt	string	Timestamp when this resource was created
updatedAt	string	Timestamp when this resource was last updated

Example

client.prompts.create(label="…", interpolation_string="…")

get

Get a prompt by ID.

def get(prompt_id: str) -> Prompt

Endpoint: GET /prompt/get/{prompt_id} · API service

Response

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

Example

client.prompts.get(prompt_id="agent-id")

delete

Delete a prompt.

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

Endpoint: DELETE /prompt/delete/{prompt_id} · API service

Response fields

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

Example

client.prompts.delete(prompt_id="agent-id")

update

Update a prompt.

def update(
    prompt_id: str,
    label: Optional[str] = None,
    interpolation_string: Optional[str] = None,
    prompt_type: Optional[str] = None,
    scope: Optional[str] = None,
    style: Optional[str] = None,
    domain: Optional[str] = None,
    prompt_placeholder: Optional[str] = None,
    available_to_agents: Optional[List[str]] = None
) -> Prompt

Endpoint: POST /prompt/update · API service

Request fields

Python kwarg	Wire field	Type	Required	Description
id	id	string	yes	Unique identifier for the prompt
workspace_id	workspaceid	string	no	Your workspace ID (UUID v4). Auto-injected by the SDK client from your configuration; you do not need to set it manually.
type	type	string	no	Prompt type classification
scope	scope	string	no	OAuth scope
style	style	string	no	Generation style: default, short, long, funny, informal, formal, interview, academic, business, creative, scientific, poetry, or news
domain	domain	string	no	Generation domain: editorial, customerService, sales, marketing, hr, finance, legal, medical, science, technology, or default
label	label	string	no	Human-readable display name
prompt_length	promptLength	integer	no	Length of the prompt in characters (32-2048)
prompt_placeholder	promptPlaceholder	string	no	Prompt placeholder text
interpolation_string	interpolationString	string	no	Prompt interpolation string
available_to_agents	availableToAgents	string	no	List of agent IDs this prompt is available to
created_by	createdBy	string	no	User ID who created the prompt
updated_by	updatedBy	string	no	User ID who last updated the prompt

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 Prompt object — fields documented in the create section above.

Example

client.prompts.update(prompt_id="agent-id")

list

List prompts.

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

Endpoint: GET /prompt/list · API service

Example

client.prompts.list()

get_by_type

Get prompts by type.

def get_by_type(prompt_type: str, limit: Optional[int] = None) -> List[Prompt]

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

Example

client.prompts.get_by_type(prompt_type="…")

get_by_agent

Get prompts available to a specific agent.

def get_by_agent(agent_id: str) -> List[Prompt]

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

Example

client.prompts.get_by_agent(agent_id="agent-id")

get_by_scope

Get prompts by scope.

def get_by_scope(scope: str) -> List[Prompt]

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

Example

client.prompts.get_by_scope(scope="…")

search

Search prompts by label.

def search(search_term: str, prompt_type: Optional[str] = None) -> List[Prompt]

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

Example

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

clone

Clone a prompt with optional modifications.

def clone(
    prompt_id: str,
    label: Optional[str] = None,
    interpolation_string: Optional[str] = None,
    prompt_type: Optional[str] = None,
    scope: Optional[str] = None,
    style: Optional[str] = None,
    domain: Optional[str] = None,
    prompt_placeholder: Optional[str] = None,
    available_to_agents: Optional[List[str]] = None
) -> Prompt

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

Example

client.prompts.clone(prompt_id="agent-id")