Skip to main content
A monitor binds one data source to one asset, runs on a schedule, and delivers every new match. The API calls it an alert rule. You build one in three moves: pick the source, describe the asset in args, and attach somewhere to send matches. Availability: every plan with a license in force. Ten data sources need a plan feature of their own, listed in Data sources. Cost: no metered allowance. Each monitor holds one Monitored Assets slot from creation until you delete it. Updates take no slot. See What your plan allows.

​
Data sources

alert_system_service_get_service_list returns the catalog of sources as a plain array, ordered by id, with no pagination.
Sources with no plan feature in the table are on every plan. Without the feature a source needs, creating or updating a monitor on it returns 403 with {"detail": "This feature is not included in your plan."}. BIN-CVV (7) and Hacker Forum DB (8) are legacy sources. Monitors already on them stay readable, editable and deletable, and the dashboard no longer offers them for new monitors. For data broker listings, use Data Brokers (17). For cards offered for sale, use Credit Card (2) with "saleCategory": "on_sale" in args. Each catalog entry tells you how to build a monitor on that source:
  • id — the value you send as service. Take it from the catalog instead of hard-coding it.
  • name — the internal key, for example phishing. Email templates show this value.
  • alias — the display label.
  • slug — the key of the matching search, for example data_broker_search.
  • is_active — whether the source runs. Monitors on an inactive source do not run.
  • args_schema — the template for the asset. See Describe the asset.
  • frequency — the fastest cadence the source allows. See How often it runs.
  • service_type — sync or async. See What a run does.
  • excludable_fields — the result fields an exclusion can match.
  • filterable_fields, sortable_fields — the result fields you can filter and sort on when you read matches.
alert_system_service_get_service_detail returns one source by id.

​
Describe the asset

args_schema has one key, params: a list of parameters, each with a name, a type, a required flag and often a hint and an example. Your monitor’s args is an object that supplies those parameters. It is the asset under watch. The platform checks args against the schema on create and update:
  • A key the schema does not define is refused: Unknown parameter 'domain' not defined in schema.
  • A missing required parameter is refused: Required parameter 'query' is missing.
  • Each value is checked against its type (Int, Float, Boolean, String, Array[…]) and any allowed values the schema lists.
  • The key createdAt is reserved and refused.
These shapes are common. The catalog’s args_schema is the full reference for each source. How lines and words in query are read. On Distinct Leak (1) and Leak Extended Search (13), the whole text is one search, and a line break counts as a space. Join words with AND: john AND doe matches both words, while john doe matches nothing. On Certificate (3), each line of query is a separate search. On Credit Card (2), a result matching any one line is enough.
Leak Filter monitors are checked before they save. Create and update ask the Filtered credentials service whether it would run the search. A domain it blocks, or a domain it has already counted at more than 5,000,000 leaked records, is refused with 400 and the service’s reason in error. A domain it has not counted yet is accepted. See Filtered credentials.

​
Create a monitor

alert_system_alert_create_alert_rule takes the source, the asset, where to deliver and an optional cadence. This monitor watches phishing references to acme.com and emails one recipient with the organization’s Default Template:
Three rules tie delivery together:
  • A monitor needs somewhere to send matches. Send a non-empty recipients list, a webhook, or both.
  • Email needs a template. When recipients is not empty, email_template is required. A webhook-only monitor needs no template and no sender.
  • Everything must be yours. Recipients, sender, template and webhook must belong to your organization.
The call returns 201 with the monitor:
The platform fills these fields:
  • id — the monitor ID. Webhook payloads carry it as alert_rule_id.
  • total_alerts_count — matches that have at least one result that is not excluded.
  • total_matches_count — results that are not excluded, across all of the monitor’s matches.
  • last_run — the end of the last window a run covered. null until the first run finishes.
  • needs_attention — true when the source rejected the monitor’s args. See What a run does.
  • is_deleted, deleted_at, deleted_by, deletion_snapshot — set when the monitor is deleted. deleted_by is the dashboard user who deleted it, and stays null when an API key deleted it.

​
What your plan allows

Two checks run before a monitor is saved, in this order. The source must be in your plan. Create and update return 403 when your plan lacks the source’s feature, when service is missing or not a number, or when it is not a known source. They return the same body when your license is not in force:
A Monitored Assets slot must be free. Every monitor that is not deleted holds one slot. When all slots are in use, create returns 409:
  • limit is your plan’s Monitored Assets plus any Extra Monitored Assets packs.
  • The count is live. Deleting a monitor frees its slot at once, and the next create succeeds.
  • Updates never take a slot, even when you change the source.
Plans and quotas explains plan features and capacity for every product.

​
How often it runs

frequency sets the cadence: Three rules decide the cadence a monitor gets:
  • A source sets a floor. A monitor never runs faster than its source’s catalog frequency. Sending a faster frequency returns 400, for example The selected frequency is more frequent than allowed. The maximum frequency for this service is Weekly.
  • Leaving frequency out uses your organization’s default. If the default is faster than the source allows, the monitor gets the source’s floor instead. Leaving it out is never refused.
  • The default applies at creation only. Changing it does not change existing monitors.
Read and change the organization default with alert_system_setting_get_organization_alert_frequency and alert_system_setting_update_organization_alert_frequency. Both use one field, default_alert_frequency, which takes the six values above. It starts as daily.

​
What a run does

  • The first run starts right away. Creating a monitor queues its first run.
  • The schedule is checked hourly. Every hour the platform starts each monitor whose interval has passed since its last run. An async monitor also waits until its previous job has finished.
  • Each run covers the time since the previous one. The first window starts when you create the monitor, so a monitor never reports results from before that moment.
  • sync sources record results during the run. async sources start a job on the source and record the results when it finishes. Unfinished jobs are checked every hour.
  • Results become a match. A run that finds nothing records no match. Telegram, Data Brokers and Domain Search keep at most 100 results on a monitor’s first run and 5,000 on later runs. Discord keeps about 5,000 per run. When a Data Brokers run hits its cap, the next run picks up the remainder.
  • Delivery needs a result that is not excluded. A match whose results are all excluded is stored but not sent.
When the source refuses a run’s request, usually because of the monitor’s args, the platform sets needs_attention to true and stops running the monitor. It resumes when you update the monitor with different args, which sets needs_attention back to false. Saving the same args again does not reset it.

​
List monitors

alert_system_alert_get_alert_rule_list returns your monitors, newest first, in pages.
The response is {count, next, previous, results}. Raise page until next is null. The next and previous URLs point at an internal service, so don’t call them. alert_system_alert_get_alert_rule_detail returns one monitor by id, deleted or not.

​
Update a monitor

alert_system_alert_update_alert_rule is a PUT with the monitor id in the path.
  • Send name, service and args every time. Optional fields you leave out keep their stored values.
  • Send delivery every time. Every update needs a non-empty recipients list or a webhook, even when the stored monitor already has one.
  • "recipients": [] removes all recipients. Send a webhook in the same call.
  • "webhook": null keeps the current webhook. You can point the monitor at another webhook. To stop webhook delivery, delete the monitor and create it again without one.
  • Update runs the create checks again. The source must be in your plan (403), args must match the schema, frequency must respect the source’s floor, and Leak Filter monitors are checked again.
  • Changing args sets needs_attention back to false.
  • A deleted monitor cannot be updated. The call returns 404.

​
Delete a monitor

alert_system_alert_delete_alert_rule stops a monitor and returns 204.
Deleting does five things:
  • Frees the monitor’s Monitored Assets slot at once.
  • Records the monitor’s last settings in deletion_snapshot, with deleted_at, and sets is_deleted to true.
  • Detaches its recipients, sender, template and webhook, so you can delete those afterwards.
  • Deletes its exclusion list.
  • Frees its name for a new monitor.
A deleted monitor stays readable through the detail endpoint and through the list with include_deleted=true. Deleting it again returns 404.

​
Errors

A missing or mistyped field other than service returns 400 with the field name as the key, for example {"name": ["This field is required."]}. A missing or non-numeric service returns 403, as described in What your plan allows. Every other 400 from create and update has an error key that holds the message, as a string or as a one-item list:

​
Endpoints