Events: list, detail, and ingest.

Events are the heartbeat of the platform: every report, advisory, and news item that flows through Liberty91 becomes an event, analysed and enriched for your account. The API lets you read those events and, just as importantly, push your own intelligence in so it gets the same treatment.

Reading requires events.read; ingesting requires events.write.

List events

GET /api/v1/events/ returns your event instances, cursor-paginated, newest first. Each item carries the tenant-level view of the event: title, criticality, TLP, and the enrichment state, plus a nested event block with the shared source item.

curl "https://api.liberty91.com/api/v1/events/" \
  -H "X-API-Key: $LIBERTY91_API_KEY"

You can filter by enrichment state with ?enrichment_status=, which is mainly useful for finding items still in flight (new, in_progress) or ones that need attention (failed).

Event detail

GET /api/v1/events/{id}/ adds the full body: the event description and content, the analysis written for your account, when that analysis was last updated, and the linked entities (threat actors, malware, vulnerabilities) and IOCs.

The description, content, and analysis fields contain rich-text HTML. If you render them outside the platform, sanitise them the way you would any HTML from an external system.

Ingest your own intelligence

This is where the API becomes a two-way street. Anything you can turn into text (a premium vendor report, a trust-group advisory, an internal incident writeup) can be ingested and enriched like any other event:

curl -X POST "https://api.liberty91.com/api/v1/events/ingest/" \
  -H "X-API-Key: $LIBERTY91_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Trust group advisory: new phishing kit targeting EU banks",
    "text": "Full text of the advisory goes here...",
    "threat_actors": [{"name": "Scattered Spider"}],
    "malwares": [],
    "vulnerabilities": [{"name": "CVE-2026-1234"}]
  }'

title and text are required. The entity arrays are optional hints: pass entries by {"id": ...} or {"name": ...} to link known entities up front, and the enrichment pipeline extracts the rest from the text itself.

The response is 202 Accepted:

{
  "event_id": "d4c3b2a1-...",
  "event_instance_id": "a1b2c3d4-...",
  "status": "new"
}

Ingested events are private to your account, and any IOCs extracted from them are marked TLP:RED. Your uploads never feed anyone else's intelligence.

Polling enrichment to completion

Ingestion kicks off background work, so you poll the detail endpoint until the enrichment settles:

Enrichment typically takes a few minutes depending on the length of the text, so poll on a relaxed interval (every 15 to 30 seconds is plenty) rather than in a tight loop. Each poll is a normal detail read and costs 1 credit; ingestion itself costs 10.

Frequently asked questions

Can I push my own intelligence into Liberty91 via the API?

Yes. POST a title and text to /api/v1/events/ingest/ and the platform creates a private event, runs the full enrichment pipeline over it, and links extracted entities and IOCs to your account.

How do I know when an ingested event has finished enriching?

Ingest returns 202 with the new event's IDs. Poll the event detail endpoint and watch enrichment_status until it reaches complete or failed.

Are ingested events visible to other Liberty91 tenants?

No. Ingested events are private to your billing account, and IOCs extracted from them are marked TLP:RED.