> For the complete documentation index, see [llms.txt](https://codemash.gitbook.io/codemash/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://codemash.gitbook.io/codemash/ai/products/ai-triggers.md).

# AI triggers

AI as a trigger source — react when the project's AI credits or a user's AI plan quota run low — and AI agents that create triggers for you.

AI costs money per use. You want to know before the bill surprises you, and your users want a warning before their chat stops: "you have used 80 % of your AI plan this month — upgrade?". Polling usage for that is waste; it is an event.

## How Norbix models it

AI is one of the five **event sources** of Norbix [triggers](/codemash/cloud/concepts/triggers.md). A trigger of type `Ai` picks one of four events and runs any trigger action — send an email, push or SMS, call a webhook, send a realtime event, run a function:

| `when`               | Fires when                                                      | Event name             |
| -------------------- | --------------------------------------------------------------- | ---------------------- |
| `OnCreditsWarning`   | the project has used 80 % of the AI credits included this month | `ai.credits.warning`   |
| `OnCreditsExhausted` | … 100 %                                                         | `ai.credits.exhausted` |
| `OnQuotaWarning`     | one end user has used 80 % of their AI plan's monthly quota     | `ai.quota.warning`     |
| `OnQuotaExhausted`   | … 100 %                                                         | `ai.quota.exhausted`   |

Quotas come from the **Plans** on Project → Settings → [AI](/codemash/cloud/project/settings/ai.md).

AI also works the other way: an AI agent can **create** triggers for you. Through the [MCP server](/codemash/ai/developers/mcp-server.md) (MCP = Model Context Protocol, the standard way AI tools call outside services), the tools `save_schema_trigger`, `save_files_trigger`, `save_membership_trigger` and `save_payments_trigger` build a trigger with an Email, Push or SMS action and ask you before they save; `save_ai_project_trigger` saves an AI trigger. There is no trigger **action** that asks an LLM (large language model) — to run AI when something happens, call your own code from a webhook or a function action.

{% hint style="warning" %}
AI triggers are **API only**: Cloud has no screen for them, and the SDK (`@norbix.ai/ts` 4.13.0) and CLI have no AI-trigger methods. Use the Hub routes below, for example with `curl` or `norbix raw`.
{% endhint %}

## Save, list and remove one

Run on a test project with an AI service user key that holds the Administrator role:

```sh
norbix raw /v3/ai/triggers -X POST --json -b '{
  "trigger": {
    "type": "Ai",
    "name": "Tell the user their AI quota is almost used",
    "isEnabled": true,
    "when": "OnQuotaWarning",
    "action": {
      "type": "ssecall",
      "deliverySettings": {
        "audience": "ToCurrentUser",
        "eventName": "ai.quota.warning",
        "payloadTemplate": "{\"text\":\"You have used 80% of your AI plan this month.\"}"
      }
    }
  }
}'
```

```json
{ "id": "trg_55s0s6OYsLb7EpqjXY6LQU", "responseStatus": { "isSuccess": true, "errors": [] } }
```

The action goes in `action` when you save. When you read a trigger back (`GET /v3/ai/triggers/{id}`) the same object comes back as `thenAction`.

| Route                                                   | What it does                                              |
| ------------------------------------------------------- | --------------------------------------------------------- |
| `POST /v3/ai/triggers`                                  | save — omit `triggerId` to create                         |
| `GET /v3/ai/triggers?projectId=…`                       | list: `type`, `viewId`, `name`, `actionType`, `isEnabled` |
| `GET /v3/ai/triggers/{id}`                              | one trigger                                               |
| `PATCH /v3/ai/triggers/{triggerId}/enable` · `/disable` | switch it on or off                                       |
| `DELETE /v3/ai/triggers/{triggerId}`                    | remove it                                                 |

```sh
norbix raw /v3/ai/triggers --json
norbix raw /v3/ai/triggers/trg_55s0s6OYsLb7EpqjXY6LQU -X DELETE --json
```

The action rules (provider, template languages, delivery settings) are the same as for every other source — see [Triggers](/codemash/cloud/concepts/triggers.md). The four AI events were not fired for this page: that needs real AI usage up to 80 % of a quota.

## Where you use it

* [Triggers](/codemash/cloud/concepts/triggers.md) — sources, actions, rules
* Project → Settings → [AI](/codemash/cloud/project/settings/ai.md) — plans and quotas
* [AI chat](/codemash/ai/products/ai-chat.md) — what uses the quota
* [What agents can do](/codemash/ai/developers/what-agents-can-do.md) — the `save_*_trigger` tools