Alerts

toothfairyai@latest…

Manager for workspace alerts.

An alert notifies recipients (in-app, push, email, webhook) when all of its conditions match. ANALYTICS alerts evaluate custom analytics fields on chats (e.g. qualityScore), SYSTEM alerts watch platform events, and CUSTOM alerts use custom field conditions.

Example:

>>> client = ToothFairyClient(api_key="...", workspace_id="...")
>>> alert = client.alerts.create(
...     name="Low quality score",
...     trigger_type="ANALYTICS",
...     conditions=[
...         {"field": "qualityScore", "operator": "lt", "value": 0.5}
...     ],
...     severity="warning",
...     notify_email=True,
... )

Accessed via client.alerts.

Methods

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

create

Create a new alert.

def create(
    name: str,
    trigger_type: AlertTriggerType,
    conditions: List[Dict[str, Any]],
    description: Optional[str] = None,
    severity: Optional[AlertSeverity] = None,
    is_active: bool = True,
    cooldown_minutes: Optional[int] = None,
    agent_id: Optional[str] = None,
    recipients: Optional[List[str]] = None,
    recipient_emails: Optional[List[str]] = None,
    notify_email: Optional[bool] = None,
    notify_push: Optional[bool] = None,
    notify_in_app: Optional[bool] = None,
    notify_webhook: Optional[bool] = None
) -> Alert

Endpoint: POST /alert/create · API service

Request fields

Python kwarg	Wire field	Type	Required	Description
`id`	`id`	`string`	no	Unique identifier
`workspace_id`	`workspaceid`	`string`	yes	Workspace ID (UUID). Must match the workspace the API key belongs to.
`name`	`name`	`string`	yes	Name of the alert
`description`	`description`	`string`	no	What this alert watches for
`trigger_type`	`triggerType`	`string`	yes	What the alert evaluates: ANALYTICS (custom analytics fields on chats), SYSTEM (platform events) or CUSTOM (custom field conditions)

Allowed: ANALYTICS, SYSTEM, CUSTOM | | conditions | conditions | string | yes | Conditions as a JSON string (AWSJSON). All conditions must match for the alert to fire. Array of {field, operator, value} entries; operator is one of: eq, neq, gt, gte, lt, lte, contains, not_contains | | severity | severity | string | no | Severity level used for alert notifications

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 alert
`description`	`string`	What this alert watches for
`triggerType`	`string`	What the alert evaluates: ANALYTICS (custom analytics fields on chats), SYSTEM (platform events) or CUSTOM (custom field conditions)

Allowed: ANALYTICS, SYSTEM, CUSTOM | | conditions | object | All conditions must match for the alert to fire. Array of {field, operator, value} entries; operator is one of: eq, neq, gt, gte, lt, lte, contains, not_contains | | severity | string | Severity level used for alert notifications

Example

client.alerts.create(name="…", trigger_type=…, conditions="…")

update

Update an alert.

def update(alert_id: str) -> Alert

Endpoint: POST /alert/update · API service

Request fields

Python kwarg	Wire field	Type	Required	Description
`id`	`id`	`string`	yes	Unique identifier
`workspace_id`	`workspaceid`	`string`	no	Workspace ID (UUID). Must match the workspace the API key belongs to.
`name`	`name`	`string`	no	Name of the alert
`description`	`description`	`string`	no	What this alert watches for
`trigger_type`	`triggerType`	`string`	no	What the alert evaluates: ANALYTICS (custom analytics fields on chats), SYSTEM (platform events) or CUSTOM (custom field conditions)

Allowed: ANALYTICS, SYSTEM, CUSTOM | | conditions | conditions | string | no | Conditions as a JSON string (AWSJSON). All conditions must match for the alert to fire. Array of {field, operator, value} entries; operator is one of: eq, neq, gt, gte, lt, lte, contains, not_contains | | severity | severity | string | no | Severity level used for alert notifications

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

Example

client.alerts.update(alert_id="agent-id")

get

Get an alert by ID.

def get(alert_id: str) -> Alert

Endpoint: GET /alert/get/{alert_id} · API service

Response

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

Example

client.alerts.get(alert_id="agent-id")

delete

Delete an alert.

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

Endpoint: DELETE /alert/delete/{alert_id} · API service

Response fields

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

Example

client.alerts.delete(alert_id="agent-id")

list

List all alerts.

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

Endpoint: GET /alert/list · API service

Response

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

Example

client.alerts.list()

pause

Pause an alert (stop evaluating and notifying).

def pause(alert_id: str) -> Alert

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

Example

client.alerts.pause(alert_id="agent-id")

resume

Resume a paused alert.

def resume(alert_id: str) -> Alert

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

Example

client.alerts.resume(alert_id="agent-id")

get_by_agent

Get alerts by agent ID.

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

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

Example

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

get_active

Get all active alerts.

def get_active() -> List[Alert]

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

Example

client.alerts.get_active()

Alerts​

Methods​

create​

Request fields​

Response fields​

Example​

update​

Request fields​

Response​

Example​

get​

Response​

Example​

delete​

Response fields​

Example​

list​

Response​

Example​

pause​

Example​

resume​

Example​

get_by_agent​

Example​

get_active​

Example​

Alerts

Methods

create

Request fields

Response fields

Example

update

Request fields

Response

Example

get

Response

Example

delete

Response fields

Example

list

Response

Example

pause

Example

resume

Example

get_by_agent

Example

get_active

Example