Event Management API Reference

Complete API documentation for integrating with KillIT v3's Event Management system.

Authentication

All API endpoints require authentication using either:

• Bearer Token: JWT token from user login
• API Token: Long-lived token for system integration

Include the token in the Authorization header:

Authorization: Bearer your-token-here

Base URL

https://your-killit-instance/api/events

Event Object

Event Schema

{
  _id: string;
  eventId: string;                    // Unique event identifier
  source: string;                     // Source system (nagios, zabbix, etc.)
  sourceId: string;                   // ID from source system
  severity: "critical" | "major" | "minor" | "warning" | "info";
  status: "open" | "acknowledged" | "resolved" | "suppressed";
  category?: string;                  // Event category
  title: string;                      // Event title
  description?: string;               // Detailed description
  timestamp: string;                  // ISO 8601 timestamp
  hostname?: string;                  // Related hostname
  ipAddress?: string;                 // Related IP address
  service?: string;                   // Service name
  application?: string;               // Application name
  environment?: string;               // Environment (prod, dev, etc.)
  correlationId?: string;             // Correlation group ID
  correlationSignature?: string;      // Signature for deduplication
  ciId?: {                           // Related Configuration Item
    _id: string;
    name: string;
    type: string;
  };
  occurrenceCount: number;           // Duplicate count (increments on deduplication)
  firstOccurrence: string;           // First seen timestamp
  lastOccurrence: string;            // Last seen timestamp (updates on duplicate)
  assignedTo?: User;                 // Assigned user
  assignedTeam?: Team;               // Assigned team
  acknowledgedBy?: User;             // Who acknowledged
  acknowledgedAt?: string;            // When acknowledged
  resolvedBy?: User;                 // Who resolved
  resolvedAt?: string;               // When resolved
  resolutionNotes?: string;          // Resolution details
  aiAnalysis?: AIAnalysis;           // AI analysis results
  businessImpact?: BusinessImpact;   // Business impact metrics
  details?: Record<string, any>;     // Additional details
  tags?: string[];                   // Event tags
  createdAt: string;                 // Creation timestamp
  updatedAt: string;                 // Last update timestamp
}

Endpoints

Ingest Single Event

Create a new event in the system.

POST /api/events/ingest
Content-Type: application/json

{
  "source": "nagios",
  "sourceId": "NAG-12345",
  "severity": "critical",
  "title": "Database Connection Failed",
  "description": "MySQL connection pool exhausted on db-prod-01",
  "timestamp": "2024-01-15T10:30:00Z",
  "hostname": "db-prod-01",
  "service": "mysql",
  "environment": "production",
  "tags": ["database", "production-issue"]
}

Response (New Event):

{
  "success": true,
  "eventId": "EVT-1234567890",
  "status": "created",
  "correlationId": "COR-987654321",
  "isDuplicate": false,
  "aiAnalysisQueued": true
}

Response (Duplicate Event):

{
  "success": true,
  "eventId": "EVT-1234567890",
  "status": "duplicate_updated",
  "correlationId": "COR-987654321",
  "isDuplicate": true,
  "aiAnalysisQueued": false,
  "occurrenceCount": 5
}

Bulk Ingest Events

Submit multiple events in a single request.

POST /api/events/bulk-ingest
Content-Type: application/json

{
  "source": "prometheus",
  "events": [
    {
      "sourceId": "PROM-001",
      "severity": "warning",
      "title": "High CPU Usage",
      "timestamp": "2024-01-15T10:30:00Z",
      "hostname": "web-01"
    },
    {
      "sourceId": "PROM-002",
      "severity": "critical",
      "title": "Service Down",
      "timestamp": "2024-01-15T10:31:00Z",
      "hostname": "web-01"
    }
  ]
}

Response:

{
  "summary": {
    "total": 2,
    "successful": 2,
    "failed": 0,
    "duplicates": 0
  },
  "results": {
    "success": [
      {"sourceId": "PROM-001", "eventId": "EVT-1234567890"},
      {"sourceId": "PROM-002", "eventId": "EVT-1234567891"}
    ],
    "failed": [],
    "duplicates": []
  }
}

Webhook Ingestion

Source-specific webhook endpoints for direct integration.

POST /api/events/webhook/{source}
Content-Type: application/json

# Source can be: nagios, zabbix, prometheus, cloudwatch, azure
# Body format depends on source system

Query Events

Retrieve events with filtering and pagination.

GET /api/events?status=open&severity=critical,major&timeRange=24h&page=1&limit=50

Query Parameters:

• status: Event status (open, acknowledged, resolved, suppressed, all)
• severity: Comma-separated severity levels
• source: Comma-separated event sources
• timeRange: Time range (1h, 6h, 24h, 3d, 7d)
• ciId: Filter by Configuration Item ID
• correlationId: Filter by correlation group
• page: Page number (default: 1)
• limit: Results per page (default: 50, max: 100)
• sortBy: Sort field (default: timestamp)
• sortOrder: Sort direction (asc, desc)

Response:

{
  "events": [...],
  "pagination": {
    "total": 145,
    "page": 1,
    "pageSize": 50,
    "totalPages": 3
  }
}

Get Event Details

Retrieve detailed information about a specific event.

GET /api/events/{eventId}

Response:

{
  "event": {
    "_id": "507f1f77bcf86cd799439011",
    "eventId": "EVT-1234567890",
    "source": "nagios",
    "severity": "critical",
    "status": "open",
    "title": "Database Connection Failed",
    // ... full event object
  },
  "correlationGroup": {
    "events": [...],
    "analysis": {
      "correlationId": "COR-987654321",
      "eventCount": 5,
      "rootCauseCandidate": {
        "eventId": "EVT-1234567889",
        "confidence": 0.85,
        "reasoning": "earliest_severe_event"
      }
    }
  }
}

Update Event Status

Change the status of an event.

PATCH /api/events/{eventId}/status
Content-Type: application/json

{
  "status": "resolved",
  "notes": "Restarted MySQL service and increased connection pool size",
  "resolutionCategory": "manual-fix"
}

Status Values:

• acknowledged: Mark as being worked on
• resolved: Mark as fixed
• suppressed: Mark as not actionable

Resolution Categories:

• auto-resolved: Automatically fixed
• manual-fix: Manually resolved
• false-positive: Not a real issue
• duplicate: Duplicate of another event
• no-action-needed: No action required

Response:

{
  "success": true,
  "event": {
    // Updated event object
  }
}

Get Event Statistics

Retrieve aggregated statistics for events.

GET /api/events/stats?timeRange=24h

Response:

{
  "timeRange": "24h",
  "stats": {
    "total": 145,
    "severityBreakdown": {
      "critical": 5,
      "major": 12,
      "minor": 45,
      "warning": 83
    },
    "openBySeverity": {
      "critical": 2,
      "major": 5
    },
    "avgResolutionTime": 3600
  }
}

Correlate Event

Manually trigger correlation analysis for a specific event using dependency, temporal, topology, and pattern strategies.

POST /api/events/{eventId}/correlate

Response:

{
  "success": true,
  "correlations": {
    "isCorrelated": true,
    "correlationId": "COR-1750135638797-abc123",
    "correlationScore": 0.9,
    "strategiesUsed": ["dependency", "temporal", "topology"],
    "correlatedEvents": [
      {
        "eventId": "68fb2d086aa9698a52774328",
        "title": "Database Process Crashed",
        "severity": "critical",
        "ciName": "HANADB01",
        "score": 0.9,
        "reasons": [
          {
            "strategy": "dependency",
            "reason": "upstream_dependency",
            "details": "SAPPRD01 depends on HANADB01"
          }
        ]
      }
    ]
  }
}

Get Event Correlations

Retrieve full correlation details and correlation group for an event.

GET /api/events/{eventId}/correlations

Response:

{
  "success": true,
  "event": {
    "_id": "68fb2d0b6aa9698a5277434f",
    "eventId": "EVT-1750135638798",
    "title": "Database Connection Lost",
    "correlationId": "COR-1750135638797-abc123",
    "parentEventId": "68fb2d086aa9698a52774328",
    "correlationMetadata": {
      "correlationType": "dependency",
      "rootCauseEvent": "68fb2d086aa9698a52774328",
      "rootCauseCI": "HANADB01",
      "confidence": 85
    }
  },
  "correlationGroup": {
    "events": [/* Array of 4 correlated events */],
    "analysis": {
      "correlationId": "COR-1750135638797-abc123",
      "eventCount": 4,
      "rootCauseCandidate": {
        "eventId": "68fb2d086aa9698a52774328",
        "confidence": 0.85,
        "reasoning": "earliest_severe_event_upstream_dependency"
      }
    }
  }
}

Analyze Recent Correlations

Analyze recent events for correlation patterns. Optionally auto-correlate events.

POST /api/events/analyze-correlations
Content-Type: application/json

{
  "hours": 24,
  "autoCorrelate": true
}

Parameters:

• hours: Lookback period in hours (default: 24)
• autoCorrelate: Automatically apply correlations (default: false)

Response:

{
  "success": true,
  "correlationGroups": 3,
  "eventsAnalyzed": 45,
  "eventsCorrelated": 12,
  "results": [
    {
      "rootCause": {
        "_id": "68fb2d086aa9698a52774328",
        "eventId": "EVT-1750135638797",
        "title": "Database Process Crashed",
        "severity": "critical",
        "ciName": "HANADB01",
        "timestamp": "2025-01-24T10:00:00Z"
      },
      "impactedEvents": [
        {
          "_id": "68fb2d0b6aa9698a5277434f",
          "eventId": "EVT-1750135638798",
          "title": "Database Connection Lost",
          "severity": "critical",
          "ciName": "SAPPRD01",
          "confidence": 0.9
        }
      ],
      "correlationId": "COR-1750135638797-abc123",
      "analysis": {
        "pattern": "database_cascade_failure",
        "totalImpact": "high",
        "affectedServices": ["SAP", "Order Processing"]
      }
    }
  ]
}

Webhook Formats

Nagios Webhook Format

{
  "notification_type": "PROBLEM",
  "hostname": "web-server-01",
  "service": "HTTP",
  "state": "CRITICAL",
  "output": "Connection refused",
  "timestamp": 1705315800
}

Zabbix Webhook Format

{
  "event_id": "12345",
  "trigger_name": "CPU usage too high",
  "trigger_description": "CPU usage over 90% for 5 minutes",
  "hostname": "app-server-01",
  "severity": "4",
  "timestamp": "2024-01-15T10:30:00Z"
}

Prometheus Alertmanager Format

{
  "alerts": [
    {
      "status": "firing",
      "labels": {
        "alertname": "HighMemoryUsage",
        "instance": "10.0.1.5:9090",
        "job": "node",
        "severity": "warning"
      },
      "annotations": {
        "summary": "High memory usage detected",
        "description": "Memory usage is above 90%"
      },
      "startsAt": "2024-01-15T10:30:00Z",
      "fingerprint": "abc123def456"
    }
  ]
}

Rate Limits

Endpoint	Rate Limit	Window
Single Event Ingestion	100 requests	1 minute
Bulk Event Ingestion	10 requests	1 minute
Webhook Endpoints	1000 requests	1 minute
Query Endpoints	100 requests	1 minute

Error Responses

400 Bad Request

{
  "error": "Validation error",
  "details": [
    {
      "field": "severity",
      "message": "Invalid severity level"
    }
  ]
}

401 Unauthorized

{
  "error": "Unauthorized",
  "message": "Invalid or missing authentication token"
}

429 Too Many Requests

{
  "error": "Rate limit exceeded",
  "message": "Too many requests, please try again later",
  "retryAfter": "2024-01-15T10:31:00Z"
}

500 Internal Server Error

{
  "error": "Internal server error",
  "message": "An unexpected error occurred"
}

Code Examples

Python Integration

import requests
import json

class KillITEventClient:
    def __init__(self, base_url, api_token):
        self.base_url = base_url
        self.headers = {
            'Authorization': f'Bearer {api_token}',
            'Content-Type': 'application/json'
        }
    
    def create_event(self, event_data):
        response = requests.post(
            f'{self.base_url}/api/events/ingest',
            headers=self.headers,
            json=event_data
        )
        return response.json()
    
    def get_events(self, filters=None):
        params = filters or {}
        response = requests.get(
            f'{self.base_url}/api/events',
            headers=self.headers,
            params=params
        )
        return response.json()

# Usage
client = KillITEventClient('https://killit.example.com', 'your-api-token')

# Create an event
event = client.create_event({
    'source': 'custom',
    'sourceId': 'APP-001',
    'severity': 'major',
    'title': 'Application Error Rate High',
    'timestamp': '2024-01-15T10:30:00Z',
    'hostname': 'app-server-01'
})

print(f"Created event: {event['eventId']}")

Node.js Integration

const axios = require('axios');

class KillITEventClient {
  constructor(baseUrl, apiToken) {
    this.client = axios.create({
      baseURL: baseUrl,
      headers: {
        'Authorization': `Bearer ${apiToken}`,
        'Content-Type': 'application/json'
      }
    });
  }
  
  async createEvent(eventData) {
    const response = await this.client.post('/api/events/ingest', eventData);
    return response.data;
  }
  
  async getEvents(filters = {}) {
    const response = await this.client.get('/api/events', { params: filters });
    return response.data;
  }
  
  async updateEventStatus(eventId, status, notes) {
    const response = await this.client.patch(`/api/events/${eventId}/status`, {
      status,
      notes
    });
    return response.data;
  }
}

// Usage
const client = new KillITEventClient('https://killit.example.com', 'your-api-token');

// Create event
const event = await client.createEvent({
  source: 'custom',
  sourceId: 'APP-001',
  severity: 'major',
  title: 'Application Error Rate High',
  timestamp: new Date().toISOString(),
  hostname: 'app-server-01'
});

console.log(`Created event: ${event.eventId}`);

Best Practices

1. Batch Events: Use bulk ingestion for multiple events
2. Include Context: Always provide hostname/IP for CI correlation
3. Use Consistent Titles: Keep event titles consistent for better deduplication
4. Avoid Dynamic Content: Remove timestamps/counters from titles
5. Provide Service Names: Include service field for accurate deduplication
6. Handle Duplicates: Check isDuplicate flag in responses
7. Monitor Occurrence Counts: High counts may indicate recurring issues
8. Use Idempotent IDs: Ensure sourceId is unique within your source system
9. Handle Rate Limits: Implement exponential backoff
10. Monitor API Health: Check response times and error rates
11. Secure Tokens: Rotate API tokens regularly
12. Validate Timestamps: Use ISO 8601 format for consistency

Next Steps

• Event Sources Configuration
• Managing Events Guide
• Troubleshooting