Payload Schema

The Ingestor accepts an array of event objects in a single POST /v1/ingest request. Each object has a kind discriminator that determines the shape of its data field.

Request structure

POST /v1/ingest
X-Device-Key: <device_key>
Content-Type: application/json

[
  { "kind": "<event_kind>", "timestamp": "<ISO8601>", "data": { ... } },
  ...
]

The request body is a JSON array. Batching multiple events in one request is expected and preferred.

Event kinds

`telemetry`

Network and system performance metrics from the Edge appliance.

{
  "kind": "telemetry",
  "timestamp": "2026-06-06T10:00:00Z",
  "data": {
    "cpu_percent": 12.5,
    "memory_percent": 45.2,
    "interface": "eth0",
    "rx_bytes": 1048576,
    "tx_bytes": 524288
  }
}

`log`

System or application log entries from the Edge appliance.

{
  "kind": "log",
  "timestamp": "2026-06-06T10:00:01Z",
  "data": {
    "level": "warn",
    "message": "High memory usage detected",
    "source": "edge-agent"
  }
}

`security_alert`

Security events detected on the Edge appliance or monitored network. Stored in security_alerts and broadcast via the /api/ws/security WebSocket hub.

{
  "kind": "security_alert",
  "timestamp": "2026-06-06T10:00:02Z",
  "data": {
    "title": "Port scan detected",
    "severity": "high",
    "source_ip": "192.168.1.100",
    "destination_ip": "10.0.0.1",
    "description": "SYN scan from 192.168.1.100 on 256 ports"
  }
}

`discovery`

Network discovery results — assets and devices found on the network segment.

{
  "kind": "discovery",
  "timestamp": "2026-06-06T10:00:03Z",
  "data": {
    "ip": "10.0.0.45",
    "mac": "AA:BB:CC:DD:EE:FF",
    "hostname": "plc-001",
    "open_ports": [102, 502, 44818],
    "vendor": "Siemens"
  }
}

`backup_event`

Backup job status events (requires Backup module enabled on the tenant).

{
  "kind": "backup_event",
  "timestamp": "2026-06-06T10:00:04Z",
  "data": {
    "job_id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "completed",
    "asset_id": "device-plc-001",
    "size_bytes": 204800,
    "checksum_sha256": "abc123..."
  }
}

Response codes

Code	Meaning
`204 No Content`	All events accepted
`400 Bad Request`	Malformed JSON or missing required fields
`401 Unauthorized`	Invalid or missing `X-Device-Key`
`413 Payload Too Large`	Batch size exceeds limit

Database storage

Ingested events are stored in the ingest_events table (V23 migration) and, for security_alert kind, also written to security_alerts with a broadcast to the Cloud Backend WebSocket hub.

The exact table schema and field mappings are defined in ingestor/internal/repository.go and migration V23__edge_ingest_events.sql.