Alerts: rules and matches.
Alert rules watch your intelligence for the conditions you care about, and the API lets you read those rules and what they matched. That is enough to route Liberty91 alerting into whatever already runs your operations: a SOAR, a ticketing queue, or a chat channel.
Rules themselves are created and managed in the platform, see Set up automatic alerting. The API is read-only here.
List alert rules
GET /api/v1/alerts/ returns your rules, cursor-paginated, each with the criteria it
matches on. Requires alerts.read.
curl "https://api.liberty91.com/api/v1/alerts/" \
-H "X-API-Key: $LIBERTY91_API_KEY"{
"next": null,
"previous": null,
"results": [
{
"id": "9a8b7c6d-3e2f-4a1b-8c7d-6e5f4a3b2c1d",
"name": "Infostealer reporting, EMEA financials",
"is_active": true,
"criteria": { "target_sectors": ["financial"], "match_logic": "ALL" }
}
]
}This list is paginated. It previously returned every rule in one response, so if you
built against an earlier draft of these docs, follow the next link. See
Pagination and errors.
Get a rule's matches
GET /api/v1/alerts/{id}/matches/ returns what the rule matched. By default those are
Threat Events: deduplicated occurrences, in the same shape as the
Threat Events list, so five write-ups of one breach arrive as
one alert rather than five.
curl "https://api.liberty91.com/api/v1/alerts/9a8b7c6d-.../matches/" \
-H "X-API-Key: $LIBERTY91_API_KEY"The envelope carries unlinked_report_count alongside the usual pagination fields: the
number of matched reports that are not attached to any of the returned occurrences, so
you can tell that the occurrence list is not the whole matched set.
{
"next": null,
"previous": null,
"unlinked_report_count": 2,
"results": [ { "id": "...", "title": "...", "verification": "corroborated" } ]
}The report shape
Pass ?results=reports for the individual reports instead, in the same shape as the
events list. That response omits unlinked_report_count, since every
matched report is returned.
curl "https://api.liberty91.com/api/v1/alerts/9a8b7c6d-.../matches/?results=reports" \
-H "X-API-Key: $LIBERTY91_API_KEY"Scopes
The matches endpoint returns another resource's data, so it needs that resource's scope as well as its own.
| Call | Scopes |
|---|---|
GET /alerts/ | alerts.read |
GET /alerts/{id}/matches/ | alerts.read and threat-events.read |
GET /alerts/{id}/matches/?results=reports | alerts.read and events.read |
Ransomware domain alerts are not alert rules
One kind of alerting does not appear here. Ransomware leak-site claims that name a domain you
care about are matched by a separate, account-level setting rather than by an AlertRule,
and are configured in billing account settings.
They are therefore absent from
GET /alerts/, and their firings are absent from /alerts/{id}/matches/. Nothing is missing
from your configuration if you cannot find them. Only an account Owner or Admin can change
that setting, and only in the app.
The API-shaped way to consume them is a webhook destination, which receives:
{
"source": "ransomware.live",
"event_id": "…",
"eventinstance_id": "…",
"billingaccount_id": "…",
"message": "<Group> claims <Victim> — matched your supplier domain example.com. UNVERIFIED leak-site CLAIM.",
"matched_kind": "supplier",
"matched_domain": "example.com",
"url": "https://platform.liberty91.com/event-instance-details/<event id>/"
}matched_kind takes supplier, asset, org_domain, or ba_domain. Exactly one alert
fires per account per claim, however many of your domains it matched, so do not use the
count of alerts as a count of exposure. Two limits shape what you will and will not receive:
domain matching is exact, so example.com matches www.example.com but not
eu.example.com, and there is no backfill for a supplier or asset added after a claim was
published.
A simple forwarding loop
- Call
GET /api/v1/alerts/and store the rules you want to forward, followingnextto the end. - On a schedule, call each rule's
matches/endpoint and compare against the Threat Event ids you have already seen. - For anything new, fetch the Threat Event detail and create the ticket, SOAR case, or chat message from its title, credibility, verification stage, and the organizations it is relevant to.
Working from Threat Events rather than reports is what keeps this loop quiet. A breach covered by six outlets raises one ticket, and later reporting on the same occurrence updates it rather than opening five more.
Rule and match reads cost 1 credit each, so even a few rules polled every five minutes stays comfortably cheap.
Frequently asked questions
Can I create alert rules through the API?
Not in v1. Rules are created and managed in the platform; the API exposes them read-only, along with their criteria and what they matched. The v1 contract is additive, so write support can arrive without breaking existing integrations.
Does an alert return reports or Threat Events?
Threat Events by default, so several write-ups of one breach arrive as one occurrence.
Pass results=reports if you specifically want the individual reports instead.
What is unlinked_report_count on an alert's matches?
The number of matched reports that are not attached to any of the returned Threat Events, so you know the occurrence list is not the whole matched set. It is only present on the default Threat Event shape.