Send events

The ingest API is for systems with no agent and no syslog: your own applications and scripts, log shippers such as Fluent Bit and Vector, CI pipelines, cloud audit trails. Windows computers use the agent, Linux servers are watched over SSH, and devices that speak syslog send it to port 514 — see Connect data sources.

Every ingest endpoint takes an API key with the ANALYST role and the write scope (see API keys and roles). Each event goes through the same pipeline as the agent’s: normalisation, the detection layers, deduplication and correlation.

Endpoints

Method and path	Body	Limit
POST /api/ingest/event	One JSON object	—
POST /api/ingest/records	A JSON array, or one JSON object per line — what Fluent Bit and Vector send	5,000 records, 10 MB
POST /api/ingest/batch	{"events": [...], "format": "json"} — format is json, syslog or cef	5,000 events
POST /api/ingest/syslog	{"line": "<34>1 2026-10-17T09:00:00Z web-01 sshd - - - Failed password for root"}	8,192 characters
POST /api/ingest/cef	{"line": "CEF:0|Vendor|Product|1.0|100|Port scan|7|src=203.0.113.7 dst=10.0.0.5"}	8,192 characters
POST /api/ingest/cloudtrail	{"records": [...]} or {"event": {...}} — AWS CloudTrail records	—
POST /api/ingest/azure-monitor	{"records": [...]} or {"event": {...}}	—
POST /api/ingest/log-file	Multipart: file, and fmt = syslog, cef, json (one object per line) or evtx	25 MB, 5,000 records

Syslog lines in RFC 5424 and RFC 3164 form are both read.

A JSON event

curl -X POST https://soc.example.com/api/ingest/event \
  -H "X-API-Key: legit_…" \
  -H "Content-Type: application/json" \
  -d '{
        "event_type": "auth_failure",
        "hostname": "web-01",
        "src_ip": "203.0.113.7",
        "message": "Failed password for root from 203.0.113.7",
        "timestamp": "2026-10-17T09:00:00Z"
      }'

This stores one failed login. On its own it does not open an alert: alerts come from the detection rules and layers — five failures from the same address followed by a success, within ten minutes, do. An event the sender marks high or critical opens one by itself.

The parser reads the field names most shippers already use, so a record rarely needs reshaping:

Meaning	Field names read, first found wins
Host	hostname, host, computer, machine, agent_hostname, ComputerName, Computer, host_name
What happened	event_type, EventID, eventType, type, action
Severity	severity, level, SeverityName, severity_label
Message	message, msg, description, event_message, log
Source address	src_ip, source_ip, src, ClientIP, ipAddress, IpAddress
Destination address	dst_ip, dest_ip, destination_ip, dst, DestinationIp

Fields inside a nested raw object are looked up too. tags and entities (strings such as user:alice) are kept as given.

Severity is one of info, low, medium, high, critical. Syslog’s words (debug, notice, warning, error, alert, emergency) are translated; a value the parser does not know is read as medium; an event sent with none is low. On a syslog line, the severity in its <PRI> is read on syslog’s own scale, from 0 (Emergency, read as critical) to 7 (Debug, read as info), except for logins, privilege changes and malware reports, where the message decides.

Time. timestamp is when the event happened, as the source reports it. The server separately records when it received the event; that time cannot be set by the sender.

Windows events. An object with EventID, event_id, or winlog.event_id (as Winlogbeat sends it) is parsed as a Windows event, with the same mapping the agent’s events get.

Linux audit. An auditd record in message is read as auditd, the same as over syslog.

Already normalised. An event with "schema_version": "legit.event.v1" and a normalized object is taken as normalised: its fields reach the rules as they are.

The response

{
  "event_id": "3eeaf0fe-60b1-46f6-9aba-edb5aa48cd81",
  "source": "web-01",
  "finding_id": null,
  "status": "ok",
  "pipeline_score": 0.0,
  "error": null
}

event_id is the stored event: GET /api/events/{event_id} returns it. source is the host, device or product the event names. finding_id is set when the event raised an alert or added to an open one, and pipeline_score is that alert’s risk score. Batch endpoints return totals instead: total, processed, findings_created, errors (each with the event’s index) and duration_ms.

When something is refused

Answer	Meaning
status: "parse_error"	The event could not be read. It is kept in the dead-letter queue (GET /api/ingest/dead-letters, ADMIN) and is not lost.
status: "pipeline_error"	The event was read but could not be stored or evaluated; error says why. Send it again.
422	A syslog or CEF line that is not syslog or CEF, a log file in an unknown format, or a batch over 5,000 events.
413	A log file over 25 MB.
429	The tenant’s daily event allowance is used up. The body says the limit, how many were sent today and when it resets; Retry-After gives the seconds to wait.

Try the pipeline

POST /api/ingest/test with {} sends one harmless test event through the whole pipeline. Use it to check a key and a connection before pointing a shipper at the API.