Triggers

Triggers

@toothfairyai/sdk@latest…

Trigger Management Module Handles CRUD operations for event-driven agent triggers.

Accessed via client.triggers.

Methods

Method	HTTP	Endpoint
create	POST	POST /trigger/create
update	POST	POST /trigger/update
delete	DELETE	DELETE /trigger/delete/{id}
get	GET	GET /trigger/get/{id}
list	GET	GET /trigger/list
pause	—	derived
resume	—	derived

create

Create a new trigger

async create(
    name: string,
    agentId: string,
    eventSourceType: 'NATIVE' | 'EXTERNAL',
    options: TriggerCreateOptions = {}
)

Endpoint: POST /trigger/create · API service

Request fields

Field	Type	Required	Description
id	string	no	Optional trigger ID (UUID). Omit to let the API generate one.
workspaceid	string	yes	Workspace ID (UUID). Must match the workspace the API key belongs to.
name	string	yes	Human-readable name for the trigger.
description	string	no	Optional description of what the trigger does.
forcedPrompt	string	no	Free-text prompt sent to the agent when the trigger fires. Provide either forcedPrompt or customPromptID, not both.
agentID	string	yes	ID of the agent that runs when the trigger fires. Voice-mode agents are not supported.
customPromptID	string	no	ID of a saved prompt (assigned to the selected agent) to send. Provide either forcedPrompt or customPromptID, not both.
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.

Allowed: NATIVE, EXTERNAL | | eventConfig | string | no | Event configuration as a JSON string (AWSJSON). The shape depends on eventSourceType.

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} | | isActive | boolean | no | true arms the trigger (status ARMED); false pauses it. | | status | string | no | Lifecycle status. Use ARMED with isActive: true for an active trigger.

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

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)

Allowed: NATIVE, EXTERNAL | | eventConfig | object | JSON-encoded event configuration. NATIVE requires eventType + optional dataFilter. EXTERNAL requires provider, providerEvent, acquisitionMode (POLLING/WEBHOOK), and pollConfig.intervalSeconds (60/120/300/600/1800) | | isActive | boolean | Whether the job is currently active | | status | string | Current status of the resource

Allowed: ARMED, PAUSED, DISABLED, FIRING, COMPLETED, FAILED, PENDING | | lastTriggeredAt | string | Timestamp when the trigger last fired | | lastEventID | string | ID of the last event that triggered this trigger | | triggerCount | integer | Number of times this trigger has fired | | executionConfig | object | JSON-encoded execution configuration | | notificationConfig | object | JSON-encoded notification configuration | | retryConfig | object | JSON-encoded retry policy configuration | | workspaceID | string | Unique workspace identifier (UUID v4) | | createdBy | string | ID of the user who created this resource | | updatedBy | string | ID of the user who last updated this resource | | createdAt | string | Timestamp when this resource was created | | updatedAt | string | Timestamp when this resource was last updated | | metadata | object | Arbitrary metadata key-value pairs (JSON) |

Example

const result = await client.triggers.create('…', 'agent-id', …);

update

Update an existing trigger

async update(triggerId: string, options: TriggerUpdateOptions = {})

Endpoint: POST /trigger/update · API service

Request fields

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

Allowed: NATIVE, EXTERNAL | | eventConfig | string | no | Event configuration as a JSON string (AWSJSON). Same shape as create — see TriggerCreateInput.eventConfig. | | isActive | boolean | no | true arms the trigger (status ARMED); false pauses it. | | status | string | no | Lifecycle status.

Allowed: ARMED, PAUSED, PENDING, RUNNING, FAILED, COMPLETED, DISABLED | | executionConfig | string | no | Execution options as a JSON string. | | notificationConfig | string | no | Notification options as a JSON string. | | retryConfig | string | no | Retry options as a JSON string. | | metadata | string | no | Free-form metadata as a JSON string. | | lastTriggeredAt | string | no | (Read-only) Timestamp of the last fire. | | lastEventID | string | no | (Read-only) ID of the last matched event. | | triggerCount | integer | no | (Read-only) Number of times the trigger has fired. | | createdBy | string | no | (Read-only) User who created the trigger. | | updatedBy | string | no | (Read-only) User who last updated the trigger. | | createdAt | string | no | (Read-only) Creation timestamp. | | updatedAt | string | no | (Read-only) Last update timestamp. |

Response

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

Example

const result = await client.triggers.update('agent-id');

delete

Delete a trigger

async delete(triggerId: string): Promise<

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

Response fields

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

Example

const result = await client.triggers.delete('agent-id');

get

Get a trigger by ID

async get(triggerId: string)

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

Response

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

Example

const result = await client.triggers.get('agent-id');

list

List all triggers in the workspace

async list(limit?: number, offset?: number)

Endpoint: GET /trigger/list · API service

Response

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

Example

const result = await client.triggers.list();

pause

Pause (disarm) a trigger

async pause(triggerId: string)

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

Example

const result = await client.triggers.pause('agent-id');

resume

Resume (arm) a paused trigger

async resume(triggerId: string)

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

Example

const result = await client.triggers.resume('agent-id');