Liberty91

IOCs: lookup, list, and export.

Last updated 10 Aug 20265 min read

The IOC endpoints expose the indicators in your account, complete with verdicts, confidence scores, TLP handling markings, and sighting timestamps. They are the natural integration point for SIEM enrichment, SOAR playbooks, and TIP synchronisation. All three endpoints require the iocs.read scope.

Note

verdict and confidence are two different judgements, and both differ again from the indicator's decaying score. The verdict is the worst reading across your enrichment vendors; confidence is how sure we are the indicator is genuinely malicious, capped low if any vendor reports it as benign.

confidence is derived at read time and is the same number the platform shows. It is null (empty in CSV) when there is genuinely no signal, meaning no extraction confidence, no vendor enrichments and no explicit verdict, rather than a misleading middling value. See IOC enrichment and decay scoring for how each is derived before you build filtering logic on them.

Two behaviours read as bugs if you meet them cold. UNKNOWN is not a weak BENIGN. AbuseIPDB below 15% confidence and Censys with no malware families on a host both write UNKNOWN deliberately, because "no signal" and "known good" are different claims: do not build allow-listing on UNKNOWN. And verdicts only escalate: a vendor returning BENIGN never overwrites a stored MALICIOUS.

Look up an indicator

Exact-match lookup for a single value:

curl "https://api.liberty91.com/api/v1/iocs/lookup/?value=evil-domain.example" \
  -H "X-API-Key: $LIBERTY91_API_KEY"

The response carries a found flag and the matching records:

{
  "value": "evil-domain.example",
  "found": true,
  "results": [
    {
      "id": "7f9e1a2b-3c4d-5e6f-8a9b-0c1d2e3f4a5b",
      "value": "evil-domain.example",
      "kind": "domain",
      "tlp": "TLP:GREEN",
      "verdict": "MALICIOUS",
      "confidence": 90,
      "tags": ["phishing", "credential-harvesting"],
      "whitelisted": false,
      "first_seen": "2026-06-02T08:30:00Z",
      "last_seen": "2026-07-05T11:15:00Z",
      "created_at": "2026-06-02T08:31:12Z",
      "source_module": "Cyber news and reports",
      "enrichment_providers": ["REVERSINGLABS", "URLSCAN"],
      "enrichments": [
        {
          "provider": "REVERSINGLABS",
          "verdict": "MALICIOUS",
          "detail": "malicious"
        },
        {
          "provider": "URLSCAN",
          "verdict": "MALICIOUS",
          "detail": "urlscan: score 78 | country NL | categories: phishing"
        }
      ]
    }
  ]
}

A miss is not an error: you get 200 with "found": false and an empty results array, which keeps enrichment pipelines simple.

Per-vendor enrichment

verdict and confidence are the merged judgement. enrichments is the working underneath it: one entry per vendor that returned something, each with the provider, that vendor's own verdict, and a short human-readable detail. The wording of detail varies by provider, because it is that provider's own headline finding: the summary line for URLScan, the bare classification for ReversingLabs. It is an empty string where the provider returned a verdict but nothing worth summarising, so treat it as display text rather than as a field to parse. enrichment_providers is the same set as a sorted list of provider codes, which is the cheaper field to filter your own storage on. Both are empty for an indicator nothing has enriched yet. The full list of provider codes is on Enumerations.

source_module names the module the indicator first arrived through, which is how you find, for example, the indicators derived from ransomware leak-site reporting. It is an empty string, not null, for an indicator with no recorded source module, which matches the platform's own CSV export.

List IOCs

GET /api/v1/iocs/ returns a cursor-paginated list, filterable along every dimension you would expect:

FilterValues
kindip, domain, url, url-path, md5, sha1, sha256, filename, other
verdictMALICIOUS, SUSPICIOUS, BENIGN, UNKNOWN
tlpEffective handling marking, for example TLP:RED
sinceISO 8601 date or datetime; returns IOCs created at or after it
searchSubstring match on the value, minimum 3 characters
whitelistedtrue or false
enrichment_providerOne provider code, for example ABUSEIPDB; returns the indicators that provider has enriched

?enrichment_provider= is the filter that makes per-vendor enrichment usable from a SIEM: ask for everything AbuseIPDB flagged, or everything your ReversingLabs appliance has seen. An unrecognised value is a 400 naming the field rather than an empty page. The filter applies to the export endpoint as well.

For example, all malicious IP addresses added in July:

curl "https://api.liberty91.com/api/v1/iocs/?kind=ip&verdict=MALICIOUS&since=2026-07-01" \
  -H "X-API-Key: $LIBERTY91_API_KEY"

See Pagination and errors for walking the full result set and the page_size parameter.

Export IOCs

For bulk transfer into another system, the export endpoint streams a file instead of a paginated list:

# CSV, up to 10,000 rows
curl "https://api.liberty91.com/api/v1/iocs/export/?format=csv" \
  -H "X-API-Key: $LIBERTY91_API_KEY" -o iocs.csv
 
# STIX 2.1 bundle, up to 5,000 objects
curl "https://api.liberty91.com/api/v1/iocs/export/?format=stix" \
  -H "X-API-Key: $LIBERTY91_API_KEY" -o iocs-bundle.json

The same filters as the list endpoint apply, so you can export exactly the slice you need. An export costs 10 credits, charged when the request is accepted; if a download is interrupted mid-transfer, rerun it, ideally with a narrower filter.

The CSV carries ten columns:

value, kind, tlp, verdict, confidence, tags, whitelisted, first_seen, last_seen, enrichment_providers

enrichment_providers is pipe-joined, for example ABUSEIPDB|GREYNOISE, and it is appended last so that a parser reading the first nine columns by position keeps working unchanged. Read by header where your parser allows it. For per-vendor detail rather than the list of names, use the JSON list or lookup endpoints: the STIX bundle carries indicator patterns and handling markings, not enrichment.

Tip

This bundle is a flat list of indicators, right for a blocklist or a bulk import, but it does not say what the indicators belong to. If you are feeding a TIP such as MISP or OpenCTI, use the parented bundles instead: /threat-events/{id}/iocs/export/ or /threat-library/{type}/{id}/iocs/export/, which carry the occurrence or entity plus relationships to each indicator.

Frequently asked questions

How do I check a single indicator against Liberty91?

Call GET /api/v1/iocs/lookup/?value= with the exact indicator value. The response tells you whether it was found and returns every matching IOC record with verdict, confidence, and TLP marking.

Can I export IOCs in STIX format?

Yes. GET /api/v1/iocs/export/?format=stix returns a STIX 2.1 bundle of up to 5,000 IOCs. CSV export supports up to 10,000 rows.

How do I pull only new IOCs since my last sync?

Pass the since filter with an ISO 8601 date or datetime to the list endpoint. Combined with cursor pagination, that gives you a clean incremental sync.

Was this page helpful?
← PreviousSearchNext →Reports: list, generate, and download