Triggers

toothfairyai@latest…

Manager for event-driven agent triggers.

Triggers invoke an agent when a configured event source fires (native ToothFairyAI events or external provider events such as Google Drive, Slack, GitHub, etc.).

Example:

>>> client = ToothFairyClient(api_key="...", workspace_id="...")
>>> trigger = client.triggers.create(
...     name="Slack mention",
...     agent_id="agent-123",
...     event_source_type="EXTERNAL",
...     event_config={"provider": "slack", "acquisitionMode": "WEBHOOK"},
... )

Accessed via client.triggers.

Methods

Method	HTTP	Endpoint
`create`	POST	`POST /trigger/create`
`update`	POST	`POST /trigger/update`
`get`	GET	`GET /trigger/get/{trigger_id}`
`delete`	DELETE	`DELETE /trigger/delete/{trigger_id}`
`list`	GET	`GET /trigger/list`
`pause`	—	derived
`resume`	—	derived
`get_by_agent`	—	derived
`get_active`	—	derived
`search`	—	derived

create

Create a new trigger.

def create(
    name: str,
    agent_id: str,
    event_source_type: Any,
    custom_prompt_id: Optional[str] = None,
    description: Optional[str] = None,
    forced_prompt: Optional[str] = None,
    event_config: Optional[Union[TriggerExternalConfig, Dict[str, Any]]] = None,
    is_active: bool = True,
    status: Optional[TriggerStatusRequest] = None,
    execution_config: Optional[Union[CronExecutionConfig, Dict[str, Any]]] = None,
    notification_config: Optional[Union[CronNotificationConfig, Dict[str, Any]]] = None,
    retry_config: Optional[Union[CronRetryConfig, Dict[str, Any]]] = None,
    metadata: Optional[Dict[str, Any]] = None
) -> Trigger

Endpoint: POST /trigger/create · API service

Request fields

Field	Type	Required	Description
`id`	`string`	no	Unique identifier
`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.
`name`	`string`	yes	Name of the resource
`description`	`string`	no	Detailed description of purpose and capabilities
`forcedPrompt`	`string`	no	Forced prompt text to use for the job (max 1024 chars)
`agentID`	`string`	yes	ID of the agent associated with this resource
`customPromptID`	`string`	no	ID of a custom prompt to use
`eventSourceType`	`string`	yes	Event source type: NATIVE (internal events) or EXTERNAL (third-party provider events)

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
`name`	`string`	Name of the resource
`description`	`string`	Detailed description of purpose and capabilities
`agentID`	`string`	ID of the agent associated with this resource
`customPromptID`	`string`	ID of a custom prompt to use
`forcedPrompt`	`string`	Forced prompt text to use for the job (max 1024 chars)
`eventSourceType`	`string`	Event source type: NATIVE (internal events) or EXTERNAL (third-party provider events)

Example

client.triggers.create(name="…", agent_id="agent-id", event_source_type=…)

update

Update a trigger.

def update(trigger_id: str) -> Trigger

Endpoint: POST /trigger/update · API service

Request fields

Field	Type	Required	Description
`id`	`string`	yes	Unique identifier
`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.
`name`	`string`	no	Name of the resource
`description`	`string`	no	Detailed description of purpose and capabilities
`forcedPrompt`	`string`	no	Forced prompt text to use for the job (max 1024 chars)
`agentID`	`string`	no	ID of the agent associated with this resource
`customPromptID`	`string`	no	ID of a custom prompt to use
`eventSourceType`	`string`	no	Event source type: NATIVE (internal events) or EXTERNAL (third-party provider events)

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

Response

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

Example

client.triggers.update(trigger_id="agent-id")

get

Get a trigger by ID.

def get(trigger_id: str) -> Trigger

Endpoint: GET /trigger/get/{trigger_id} · API service

Response

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

Example

client.triggers.get(trigger_id="agent-id")

delete

Delete a trigger.

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

Endpoint: DELETE /trigger/delete/{trigger_id} · API service

Response fields

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

Example

client.triggers.delete(trigger_id="agent-id")

list

List all triggers.

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

Endpoint: GET /trigger/list · API service

Response

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

Example

client.triggers.list()