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

Python kwarg	Wire field	Type	Required	Description
`id`	`id`	`string`	no	Optional trigger ID (UUID). Omit to let the API generate one.
`workspace_id`	`workspaceid`	`string`	yes	Workspace ID (UUID). Must match the workspace the API key belongs to.
`name`	`name`	`string`	yes	Human-readable name for the trigger.
`description`	`description`	`string`	no	Optional description of what the trigger does.
`forced_prompt`	`forcedPrompt`	`string`	no	Free-text prompt sent to the agent when the trigger fires. Provide either `forcedPrompt` or `customPromptID`, not both.
`agent_id`	`agentID`	`string`	yes	ID of the agent that runs when the trigger fires. Voice-mode agents are not supported.
`custom_prompt_id`	`customPromptID`	`string`	no	ID of a saved prompt (assigned to the selected agent) to send. Provide either `forcedPrompt` or `customPromptID`, not both.
`event_source_type`	`eventSourceType`	`string`	yes	`NATIVE` fires on ToothFairyAI's own platform events (document lifecycle, agent, planner). `EXTERNAL` fires on third-party provider events acquired by polling.

NATIVE — filters on the event payload (dataFilter rows all must match; operators: equals, not equals, includes, greater than, less than, exists): {"eventType":"document.created","eventCategory":"documents","dataFilter":[{"field":"topics","op":"includes","value":"<topicID>"}]}

EXTERNAL — provider + provider event (valid pairs are served by the trigger catalog endpoint GET /triggers/catalog, which lists every provider, its events, partner event names and sample payloads): {"provider":"googleDrive","providerEvent":"drive.file.created","pollIntervalMins":5} | | is_active | isActive | boolean | no | true arms the trigger (status ARMED); false pauses it. | | status | status | string | no | Lifecycle status. Use ARMED with isActive: true for an active trigger.

Allowed: ARMED, PAUSED, PENDING, RUNNING, FAILED, COMPLETED, DISABLED | | execution_config | executionConfig | string | no | Execution options as a JSON string, e.g. {"timeout":30,"maxDuration":300,"priority":"normal"}. | | notification_config | notificationConfig | string | no | Notification options as a JSON string, e.g. {"onSuccess":true,"onFailure":true,"emailRecipients":[]}. | | retry_config | retryConfig | string | no | Retry options as a JSON string, e.g. {"maxRetries":3,"retryInterval":60}. | | metadata | metadata | string | no | Free-form metadata as a JSON string. | | last_triggered_at | lastTriggeredAt | string | no | (Read-only) Timestamp of the last fire. | | last_event_id | lastEventID | string | no | (Read-only) ID of the last matched event, used by the dispatcher for idempotency. | | trigger_count | triggerCount | integer | no | (Read-only) Number of times the trigger has fired. | | created_by | createdBy | string | no | (Read-only) User who created the trigger. | | updated_by | updatedBy | string | no | (Read-only) User who last updated the trigger. | | created_at | createdAt | string | no | (Read-only) Creation timestamp. | | updated_at | updatedAt | string | no | (Read-only) Last update timestamp. |

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
`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

Python kwarg	Wire field	Type	Required	Description
`id`	`id`	`string`	yes	ID of the trigger to update (from `/trigger/create` or `/trigger/list`).
`workspace_id`	`workspaceid`	`string`	no	Workspace ID (UUID). Must match the workspace the API key belongs to.
`name`	`name`	`string`	no	Human-readable name for the trigger.
`description`	`description`	`string`	no	Optional description of what the trigger does.
`forced_prompt`	`forcedPrompt`	`string`	no	Free-text prompt sent to the agent when the trigger fires. Provide either `forcedPrompt` or `customPromptID`, not both.
`agent_id`	`agentID`	`string`	no	ID of the agent that runs when the trigger fires. Voice-mode agents are not supported.
`custom_prompt_id`	`customPromptID`	`string`	no	ID of a saved prompt (assigned to the selected agent) to send. Provide either `forcedPrompt` or `customPromptID`, not both.
`event_source_type`	`eventSourceType`	`string`	no	`NATIVE` fires on ToothFairyAI's own platform events. `EXTERNAL` fires on third-party provider events acquired by polling.

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 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()