> ## Documentation Index
> Fetch the complete documentation index at: https://moonshotfactory.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Alerts

> Create and manage alert rules that fire when agent or infrastructure conditions are met.

Alerts let you define threshold-based rules that send notifications when an agent or service crosses a condition. Each alert targets either an agent by UUID or a service by name, and delivers notifications over email, webhook, or both.

***

## Alert types

| Type                | Threshold meaning                                                                       |
| ------------------- | --------------------------------------------------------------------------------------- |
| `failure_rate`      | Fraction `0.0–1.0` — fires when the failure rate exceeds this value (e.g. `0.20` = 20%) |
| `inactivity`        | Hours — fires when the agent has not run for this many hours                            |
| `cost_threshold`    | USD — fires when the daily cost exceeds this amount                                     |
| `latency_threshold` | Milliseconds — fires when p95 latency exceeds this value                                |
| `composite`         | Uses `composite_config` — fires when combined AI + infrastructure conditions are met    |

## Delivery channels

| Channel   | Behavior                                         |
| --------- | ------------------------------------------------ |
| `email`   | Sends an email to your account address (default) |
| `webhook` | Posts to your `webhook_url`                      |
| `both`    | Sends both email and webhook                     |

***

## List alerts

<CodeGroup>
  ```bash cURL theme={null}
  curl https://api.agentvista.dev/api/v1/alerts \
    -H "Authorization: Bearer av_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
  ```
</CodeGroup>

`GET /alerts`

Returns all alerts associated with agents belonging to the authenticated user.

### Response — 200

An array of alert objects.

<ResponseField name="id" type="string">
  Alert UUID.
</ResponseField>

<ResponseField name="agent_id" type="string | null">
  UUID of the target agent, or `null` for service-targeted alerts.
</ResponseField>

<ResponseField name="agent_name" type="string | null">
  Name of the target agent, or `null`.
</ResponseField>

<ResponseField name="type" type="string">
  Alert type: `failure_rate`, `inactivity`, `cost_threshold`, `latency_threshold`, or `composite`.
</ResponseField>

<ResponseField name="threshold" type="number">
  Threshold value. Semantics depend on the alert type.
</ResponseField>

<ResponseField name="cooldown_minutes" type="number">
  Minimum minutes between consecutive firings of this alert.
</ResponseField>

<ResponseField name="is_active" type="boolean">
  Whether this alert is currently enabled.
</ResponseField>

<ResponseField name="channel" type="string">
  Delivery channel: `email`, `webhook`, or `both`.
</ResponseField>

<ResponseField name="webhook_url" type="string | null">
  Webhook delivery URL. Present when `channel` is `webhook` or `both`.
</ResponseField>

<ResponseField name="composite_config" type="object | null">
  Composite rule definition. Present only for `composite` type alerts.
</ResponseField>

<ResponseField name="target_service" type="string | null">
  Service name for service-targeted alerts. Null for agent-targeted alerts.
</ResponseField>

<ResponseField name="last_fired_at" type="string | null">
  ISO 8601 timestamp of the last time this alert fired.
</ResponseField>

<ResponseField name="created_at" type="string">
  ISO 8601 timestamp when this alert was created.
</ResponseField>

***

## Create an alert

<CodeGroup>
  ```bash Failure rate alert theme={null}
  curl -X POST https://api.agentvista.dev/api/v1/alerts \
    -H "Authorization: Bearer av_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
    -H "Content-Type: application/json" \
    -d '{
      "agent_id": "3a7f8c2d-1e4b-4a9d-b8e2-5f6c7d8e9f0a",
      "type": "failure_rate",
      "threshold": 0.20,
      "cooldown_minutes": 60,
      "channel": "email"
    }'
  ```

  ```bash Cost threshold with webhook theme={null}
  curl -X POST https://api.agentvista.dev/api/v1/alerts \
    -H "Authorization: Bearer av_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
    -H "Content-Type: application/json" \
    -d '{
      "agent_id": "3a7f8c2d-1e4b-4a9d-b8e2-5f6c7d8e9f0a",
      "type": "cost_threshold",
      "threshold": 50.00,
      "cooldown_minutes": 1440,
      "channel": "both",
      "webhook_url": "https://hooks.example.com/agentvista-cost"
    }'
  ```

  ```bash Composite alert theme={null}
  curl -X POST https://api.agentvista.dev/api/v1/alerts \
    -H "Authorization: Bearer av_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
    -H "Content-Type: application/json" \
    -d '{
      "agent_id": "3a7f8c2d-1e4b-4a9d-b8e2-5f6c7d8e9f0a",
      "type": "composite",
      "threshold": 0,
      "cooldown_minutes": 60,
      "channel": "email",
      "composite_config": {
        "operator": "and",
        "conditions": [
          { "type": "failure_rate", "source": "ai", "threshold": 0.15 },
          { "type": "metric_threshold", "source": "infra", "metric_name": "system.cpu.utilization", "operator": "gt", "value": 0.90 }
        ]
      }
    }'
  ```
</CodeGroup>

`POST /alerts`

Creates an alert rule. Either `agent_id` or `target_service` must be provided. Validation rules:

* `failure_rate`, `inactivity`, `cost_threshold`, and `latency_threshold` alerts require a `threshold` value.
* `composite` alerts require a valid `composite_config` with at least one `ai` condition and one `infra` condition.
* Alerts with `channel` of `webhook` or `both` require a `webhook_url`.

### Request body

<ParamField body="agent_id" type="string">
  UUID of the agent to monitor. Either `agent_id` or `target_service` must be provided.
</ParamField>

<ParamField body="target_service" type="string">
  Service name to monitor (for infrastructure-only alerts). Either `agent_id` or `target_service` must be provided.
</ParamField>

<ParamField body="type" type="string" required>
  Alert type: `failure_rate`, `inactivity`, `cost_threshold`, `latency_threshold`, or `composite`.
</ParamField>

<ParamField body="threshold" type="number" default="0">
  Threshold value. Required for all types except `composite`. See the alert types table for semantics.
</ParamField>

<ParamField body="cooldown_minutes" type="number" default="60">
  Minimum minutes between consecutive firings of this alert.
</ParamField>

<ParamField body="channel" type="string" default="email">
  Delivery channel: `email`, `webhook`, or `both`.
</ParamField>

<ParamField body="webhook_url" type="string">
  HTTPS URL to deliver webhook notifications to. Required when `channel` is `webhook` or `both`.
</ParamField>

<ParamField body="composite_config" type="object">
  Composite alert rule. Required when `type` is `composite`.

  <Expandable title="composite_config fields">
    <ParamField body="operator" type="string" required>
      How to combine conditions: `"and"` (all must fire) or `"or"` (any must fire).
    </ParamField>

    <ParamField body="conditions" type="object[]" required>
      Array of conditions. Must include at least one `ai` source condition and one `infra` source condition.

      <Expandable title="condition fields">
        <ParamField body="type" type="string" required>
          Condition type: `failure_rate`, `inactivity`, `cost_threshold`, or `metric_threshold`.
        </ParamField>

        <ParamField body="source" type="string" required>
          Signal source: `"ai"` (agent traces) or `"infra"` (infrastructure metrics).
        </ParamField>

        <ParamField body="threshold" type="number">
          Threshold value. Used for `failure_rate`, `cost_threshold`, and `inactivity` conditions.
        </ParamField>

        <ParamField body="metric_name" type="string">
          Metric name to query. Used for `metric_threshold` conditions.
        </ParamField>

        <ParamField body="operator" type="string">
          Comparison operator for `metric_threshold`: `"gt"`, `"lt"`, `"gte"`, or `"lte"`.
        </ParamField>

        <ParamField body="value" type="number">
          Value to compare against. Used for `metric_threshold` conditions.
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

### Response — 201

Returns the created alert object. Same schema as the list response.

***

## Get an alert

<CodeGroup>
  ```bash cURL theme={null}
  curl https://api.agentvista.dev/api/v1/alerts/7c3f9a1b-2d5e-4f8a-9b0c-1d2e3f4a5b6c \
    -H "Authorization: Bearer av_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
  ```
</CodeGroup>

`GET /alerts/{alert_id}`

Returns a single alert. Returns `404` if the alert does not belong to the authenticated user.

### Path parameters

<ParamField path="alert_id" type="string" required>
  UUID of the alert.
</ParamField>

### Response — 200

Same schema as a single item from the [list response](#list-alerts).

***

## Update an alert

<CodeGroup>
  ```bash Pause an alert theme={null}
  curl -X PATCH https://api.agentvista.dev/api/v1/alerts/7c3f9a1b-2d5e-4f8a-9b0c-1d2e3f4a5b6c \
    -H "Authorization: Bearer av_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
    -H "Content-Type: application/json" \
    -d '{"is_active": false}'
  ```

  ```bash Update threshold theme={null}
  curl -X PATCH https://api.agentvista.dev/api/v1/alerts/7c3f9a1b-2d5e-4f8a-9b0c-1d2e3f4a5b6c \
    -H "Authorization: Bearer av_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
    -H "Content-Type: application/json" \
    -d '{"threshold": 0.25, "cooldown_minutes": 120}'
  ```
</CodeGroup>

`PATCH /alerts/{alert_id}`

Updates one or more mutable fields on an alert. All fields are optional — omit any fields you do not want to change.

### Path parameters

<ParamField path="alert_id" type="string" required>
  UUID of the alert.
</ParamField>

### Request body

<ParamField body="threshold" type="number">
  New threshold value.
</ParamField>

<ParamField body="cooldown_minutes" type="number">
  New cooldown period in minutes.
</ParamField>

<ParamField body="is_active" type="boolean">
  Set to `false` to pause the alert, `true` to re-enable it.
</ParamField>

<ParamField body="channel" type="string">
  New delivery channel: `email`, `webhook`, or `both`.
</ParamField>

<ParamField body="webhook_url" type="string">
  New webhook URL.
</ParamField>

### Response — 200

Returns the updated alert object.

***

## Delete an alert

<CodeGroup>
  ```bash cURL theme={null}
  curl -X DELETE https://api.agentvista.dev/api/v1/alerts/7c3f9a1b-2d5e-4f8a-9b0c-1d2e3f4a5b6c \
    -H "Authorization: Bearer av_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
  ```
</CodeGroup>

`DELETE /alerts/{alert_id}`

Permanently deletes an alert and all its associated events. This action is irreversible.

### Path parameters

<ParamField path="alert_id" type="string" required>
  UUID of the alert to delete.
</ParamField>

### Response — 204

No body. The alert has been deleted.