Events API

The Events API lets you query security events, submit custom events, and manage event data programmatically.

List Events

GET /v1/events

Query Parameters:
  page          integer   Page number (default: 1)
  per_page      integer   Results per page (default: 25, max: 100)
  employee_id   string    Filter by employee
  type          string    Filter by event type
  source        string    Filter by source integration
  from          string    Start date (ISO 8601)
  to            string    End date (ISO 8601)
  impact        string    Filter by impact direction (positive, negative)

Response:
{
  "data": [
    {
      "id": "evt_abc123",
      "type": "sim.link_clicked",
      "source": "tidalbay_phishing",
      "employee_id": "emp_xyz789",
      "employee_email": "john.doe@company.com",
      "impact": -25,
      "current_impact": -18.5,
      "timestamp": "2025-01-15T10:30:00Z",
      "details": {
        "campaign": "Q1 2025 Phishing Test",
        "template": "invoice_payment"
      },
      "rules_matched": ["rule_phishing_click"]
    }
  ],
  "pagination": { ... }
}

Get Event

GET /v1/events/:id

Submit Custom Event

POST /v1/events

Body:
{
  "type": "custom.policy_violation",
  "employee_email": "john.doe@company.com",
  "timestamp": "2025-01-15T10:30:00Z",
  "details": {
    "description": "Accessed restricted file share",
    "severity": "medium",
    "source_system": "dlp-monitor"
  }
}

Response:
{
  "id": "evt_new456",
  "type": "custom.policy_violation",
  "employee_id": "emp_xyz789",
  "impact": -15,
  "rules_matched": ["rule_policy_violation"],
  "score_before": 72,
  "score_after": 57
}
Custom Event Scoring
Custom events are evaluated against your scoring rules just like integration events. Create rules with event_type: custom.* to handle custom events. See Rules API.

Get Event Statistics

GET /v1/events/statistics

Query Parameters:
  from        string    Start date
  to          string    End date
  group_by    string    Group by: type, source, department

Response:
{
  "data": [
    {
      "type": "sim.link_clicked",
      "count": 145,
      "affected_employees": 120,
      "average_impact": -25
    },
    {
      "type": "email.phishing_reported",
      "count": 312,
      "affected_employees": 280,
      "average_impact": +10
    }
  ]
}

Next Steps