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

# Create a monitoring rule

> Create a monitoring rule — pick a data source, hand it your asset, set the cadence, and attach delivery.

A monitoring rule is the unit of monitoring: it binds one **data source** (an alert *service*) to one **asset** (the `args`), runs on a **schedule**, and **delivers** every new match. Build it in three moves — choose the source, describe the asset, attach delivery.

### Pick a data source

The sources you can monitor are the **alert service catalog**. List it with [`alert_system_service_get_service_list`](https://client-api.leak.center/scalar-docs/#tag/alert-system/GET/service/alert_system_service_get_service_list/) (no pagination). There are 15 services, each backed by an indexed source — Telegram, Discord, Leak Filter (filtered credentials), Leak Extended Search (raw leaks), Distinct Leak, Credit Card, BIN-CVV, Phishing, Certificate, Ransomware, Hacker Forum, Pastebin, App Stores, Bucket (cloud storage), and Shortener.

Each service row tells you how to use it:

* `id` — the value you pass as `service` when creating a rule.
* `name`, `alias` — the internal key and the human-readable label.
* `args_schema` — **the template for the asset you'll monitor** (see below).
* `service_type` — `sync` (results land on the next run) or `async` (a background job finishes later).
* `excludable_fields`, `filterable_fields`, `sortable_fields` — which result fields you can [exclude](/api/guides/monitoring-exclusions), filter, and sort when [reading matches](/api/guides/monitoring-matches).
* `frequency` — the source's floor cadence; a rule can't run faster than this.

### Describe the asset: `args` and `args_schema`

`args_schema` is a JSON template, `{"params": [ … ]}`, where each param declares a `name`, a `type`, whether it's `required`, and an optional `hint`/`example`. Your rule's `args` is the concrete value you supply for those params — that's the asset you're putting under watch.

A few real shapes from the catalog:

| Service     | `args_schema` params                                                                | Example `args`                               |
| ----------- | ----------------------------------------------------------------------------------- | -------------------------------------------- |
| Phishing    | `domain` (String, required)                                                         | `{"domain": "acme.com"}`                     |
| Telegram    | `query` (String, required) + optional `channel_ids`, `unique_only`, `context_chars` | `{"query": "acme.com"}`                      |
| Leak Filter | `domain_url` (required), `filter_id` (required), `filter_parameters` (optional)     | `{"domain_url": "acme.com", "filter_id": 5}` |

`args` is validated against the service's `args_schema` server-side: unknown keys are rejected, missing required params are rejected, and each value is type-checked (`Int`, `Float`, `Boolean`, `String`, `Array[…]`) and constrained to any declared valid values. (The key `createdAt` is reserved and not allowed.) Discover the exact params for a service by reading its `args_schema` from the catalog — the values aren't fixed in code; they're configured per source.

### Create the rule

[`alert_system_alert_create_alert_rule`](https://client-api.leak.center/scalar-docs/#tag/alert-system/POST/service/alert_system_alert_create_alert_rule/) takes the source, the asset, delivery, and an optional cadence:

```bash theme={"dark"}
curl https://client-api.leak.center/api/service/alert_system_alert_create_alert_rule/ \
  -X POST \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
        "name": "Acme phishing watch",
        "service": 3,
        "args": { "domain": "acme.com" },
        "recipients": [12],
        "sender": 8,
        "email_template": 5,
        "webhook": 2,
        "frequency": "daily"
      }'
```

| Field            | Type          | Required | Notes                                                                                |
| ---------------- | ------------- | -------- | ------------------------------------------------------------------------------------ |
| `name`           | string (≤255) | yes      | Unique within your organization.                                                     |
| `service`        | integer       | yes      | A service `id` from the catalog.                                                     |
| `args`           | object        | yes      | The asset — must satisfy the service's `args_schema`.                                |
| `sender`         | integer       | no       | A [sender](/api/guides/monitoring-delivery) `id`. Optional — may be omitted or null. |
| `email_template` | integer       | yes      | A [template](/api/guides/monitoring-delivery) `id`.                                  |
| `recipients`     | array of int  | no       | [Recipient](/api/guides/monitoring-delivery) `id`s; may be empty.                    |
| `webhook`        | integer       | no       | A [webhook](/api/guides/monitoring-delivery) `id`, or null.                          |
| `frequency`      | string        | no       | Defaults to your org's setting (below).                                              |

One cross-field rule: **a rule needs somewhere to send matches** — at least one of `recipients` or `webhook` must be set. `email_template` is required on create; **`sender` is optional and may be null** — including for a webhook-only rule. The sender, template, webhook, and recipients must all belong to your organization. Organizations have an `alert_rule_limit`; creating past it is rejected.

A `201` returns the full rule with its read-only fields: `id`, `total_alerts_count`, `total_matches_count` (both count non-excluded results), `created_at`, `updated_at`, `last_run`, and the soft-delete fields `is_deleted`, `deleted_at`, `deleted_by`, `deletion_snapshot`.

### How often it runs

Set the cadence with `frequency`:

| `frequency`       | Runs about     | Hours |
| ----------------- | -------------- | ----- |
| `daily` (default) | once a day     | 24    |
| `twice_weekly`    | every 3–4 days | 84    |
| `weekly`          | once a week    | 168   |
| `biweekly`        | every 2 weeks  | 336   |
| `twice_monthly`   | twice a month  | 360   |
| `monthly`         | once a month   | 720   |

Two things shape the real cadence. The **effective frequency is the slower of your rule's `frequency` and the service's own floor** — a rule can't run faster than its source allows, and a frequency faster than the floor is rejected. And if you omit `frequency`, it inherits your [organization default](/api/guides/monitoring-metrics) (also `daily` out of the box).

### What a run does

* On **create**, the rule runs once immediately.
* After that it's evaluated every hour; it actually runs only when enough time has passed for its effective frequency.
* Each run looks at the window **since the last run** (`last_run` → now) and keeps only hits newer than that. New hits become a [match](/api/guides/monitoring-matches); an empty run records nothing and just advances `last_run`.
* **Sync** services persist results on the spot. **Async** services kick off a background job and fill the match in when it completes.
* A notification fires only when a run produces at least one *non-excluded* new hit.

### Manage rules

* **List** — [`alert_system_alert_get_alert_rule_list`](https://client-api.leak.center/scalar-docs/#tag/alert-system/GET/service/alert_system_alert_get_alert_rule_list/), a paginated envelope (`{count, next, previous, results}` — page through `next`). Filter with `recipient_id`, `sender_id`, `email_template_id`, and `webhook_id` (each returns the rules attached to that entity). Pass `include_deleted=true` to include soft-deleted rules; otherwise only active rules return.
* **Update** — [`alert_system_alert_update_alert_rule`](https://client-api.leak.center/scalar-docs/#tag/alert-system/PUT/service/alert_system_alert_update_alert_rule/\{id}/) is a full `PUT`: send the complete rule body, not just the changed fields.
* **Delete** — [`alert_system_alert_delete_alert_rule`](https://client-api.leak.center/scalar-docs/#tag/alert-system/DELETE/service/alert_system_alert_delete_alert_rule/\{id}/) is a **soft delete**: it sets `is_deleted`, snapshots the rule into `deletion_snapshot`, and detaches its recipients, sender, template, webhook, and exclusions. Deleted rules reappear only under `include_deleted=true`.