Console API

Console API Reference

REST API endpoints for the KYRA MDR management console, providing programmatic access to all platform capabilities.

All APIs are tenant-aware and enforce tenant isolation through JWT-based authentication.

Base URL: https://api.kyra-mdr.com/v1

Authentication: Bearer JWT token in Authorization header

1. Connector Management APIs

GET /connectors

List all connectors for tenant

Response:

{
  "connectors": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Primary Data Source",
      "type": "siem",
      "status": "healthy",
      "enabled": true,
      "health": {
        "last_check": "2026-02-20T10:30:00Z",
        "message": "Connected, receiving events",
        "consecutive_failures": 0
      },
      "stats": {
        "events_received_total": 125430,
        "events_failed_total": 12,
        "bytes_received_total": 45678900,
        "events_per_second": 42.5,
        "last_event_at": "2026-02-20T10:30:15Z"
      },
      "config": {
        "url": "https://siem.internal.example.com",
        "polling_interval": "30s"
      },
      "created_at": "2026-01-15T08:00:00Z",
      "updated_at": "2026-02-20T10:30:00Z"
    }
  ]
}

GET /connectors/{id}/health

Get detailed health status for a connector

Response:

{
  "connector_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "healthy",
  "last_check": "2026-02-20T10:30:00Z",
  "checks": [
    {
      "type": "connectivity",
      "status": "pass",
      "message": "Connection established",
      "latency_ms": 45
    },
    {
      "type": "authentication",
      "status": "pass",
      "message": "API key valid"
    },
    {
      "type": "data_flow",
      "status": "pass",
      "message": "Receiving events",
      "events_in_last_minute": 85
    }
  ],
  "history": [
    {
      "timestamp": "2026-02-20T10:30:00Z",
      "status": "healthy"
    },
    {
      "timestamp": "2026-02-20T10:25:00Z",
      "status": "healthy"
    }
  ]
}

GET /connectors/{id}/metrics

Get time-series metrics for a connector (for charts)

Query params:

from: ISO 8601 timestamp (default: 1 hour ago)
to: ISO 8601 timestamp (default: now)
interval: Aggregation interval (1m, 5m, 15m, 1h)

Response:

{
  "connector_id": "550e8400-e29b-41d4-a716-446655440000",
  "metrics": {
    "events_received": [
      {"timestamp": "2026-02-20T10:00:00Z", "value": 2550},
      {"timestamp": "2026-02-20T10:05:00Z", "value": 2680},
      {"timestamp": "2026-02-20T10:10:00Z", "value": 2420}
    ],
    "events_failed": [
      {"timestamp": "2026-02-20T10:00:00Z", "value": 2},
      {"timestamp": "2026-02-20T10:05:00Z", "value": 1},
      {"timestamp": "2026-02-20T10:10:00Z", "value": 0}
    ],
    "throughput_eps": [
      {"timestamp": "2026-02-20T10:00:00Z", "value": 42.5},
      {"timestamp": "2026-02-20T10:05:00Z", "value": 44.7},
      {"timestamp": "2026-02-20T10:10:00Z", "value": 40.3}
    ]
  }
}

POST /connectors

Create a new connector

Request:

{
  "name": "Production CrowdStrike",
  "type": "crowdstrike",
  "enabled": true,
  "config": {
    "client_id": "abc123...",
    "client_secret": "secret...",
    "base_url": "https://api.crowdstrike.com",
    "polling_interval": "30s"
  }
}

PUT /connectors/{id}

Update connector configuration

DELETE /connectors/{id}

Delete a connector

POST /connectors/{id}/test

Test connector connectivity before saving

2. Event Pipeline Monitoring APIs

GET /pipeline/metrics

Get overall pipeline metrics

Response:

{
  "timestamp": "2026-02-20T10:30:00Z",
  "stages": {
    "ingestion": {
      "events_total": 1250000,
      "events_per_second": 125.5,
      "active_connectors": 5,
      "healthy_connectors": 5
    },
    "normalization": {
      "events_processed": 1248500,
      "events_failed": 50,
      "success_rate": 99.96,
      "avg_latency_ms": 12.5,
      "p99_latency_ms": 45
    },
    "detection": {
      "events_evaluated": 1248500,
      "rules_matched": 1250,
      "alerts_generated": 856,
      "false_positives": 394,
      "avg_evaluation_time_ms": 8.2
    },
    "enrichment": {
      "alerts_processed": 856,
      "avg_enrichment_time_ms": 150,
      "intel_cache_hit_rate": 78.5
    }
  },
  "queue": {
    "topics": [
      {
        "name": "normalized-events",
        "consumer_lag": 1250,
        "messages_per_second": 125.5
      },
      {
        "name": "alerts",
        "consumer_lag": 45,
        "messages_per_second": 1.4
      }
    ]
  }
}

GET /pipeline/metrics/timeseries

Get time-series data for pipeline metrics (for charts)

Query params:

from, to, interval (same as connector metrics)

Response:

{
  "ingestion_rate": [
    {"timestamp": "2026-02-20T10:00:00Z", "value": 120.5},
    {"timestamp": "2026-02-20T10:05:00Z", "value": 125.2}
  ],
  "normalization_latency": [
    {"timestamp": "2026-02-20T10:00:00Z", "p50": 10.2, "p95": 35.5, "p99": 48.2},
    {"timestamp": "2026-02-20T10:05:00Z", "p50": 12.5, "p95": 38.1, "p99": 45.0}
  ],
  "alerts_generated": [
    {"timestamp": "2026-02-20T10:00:00Z", "value": 45},
    {"timestamp": "2026-02-20T10:05:00Z", "value": 52}
  ],
  "queue_consumer_lag": {
    "normalized-events": [
      {"timestamp": "2026-02-20T10:00:00Z", "value": 1500},
      {"timestamp": "2026-02-20T10:05:00Z", "value": 1250}
    ]
  }
}

3. Detection Engine APIs

GET /detection/rules

List detection rules

Query params:

level: Filter by severity (low, medium, high, critical)
enabled: Filter by status (true/false)
tactic: Filter by MITRE tactic
technique: Filter by MITRE technique
page, size: Pagination

Response:

{
  "rules": [
    {
      "id": "fb843269-508c-4b76-8b8d-88679db22ce7",
      "title": "Suspicious Encoded PowerShell Command",
      "level": "high",
      "status": "stable",
      "enabled": true,
      "logsource": {
        "category": "process_creation",
        "product": "windows"
      },
      "mitre": {
        "tactics": ["execution"],
        "techniques": ["T1059.001"]
      },
      "stats": {
        "evaluations_total": 125000,
        "matches_total": 45,
        "true_positives": 38,
        "false_positives": 7,
        "match_rate": 0.036
      },
      "created_at": "2026-01-15T08:00:00Z",
      "updated_at": "2026-02-10T14:30:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "size": 50,
    "total": 450
  }
}

GET /detection/rules/{id}

Get detailed rule information

Response:

{
  "id": "fb843269-508c-4b76-8b8d-88679db22ce7",
  "title": "Suspicious Encoded PowerShell Command",
  "description": "Detects suspicious PowerShell command with base64 encoded arguments",
  "level": "high",
  "status": "stable",
  "author": "Florian Roth",
  "date": "2018-03-05",
  "modified": "2023-01-05",
  "logsource": {
    "category": "process_creation",
    "product": "windows"
  },
  "mitre": {
    "tactics": ["execution"],
    "techniques": ["T1059.001"]
  },
  "false_positives": ["Unknown"],
  "references": [
    "https://attack.mitre.org/techniques/T1059/001/"
  ],
  "tags": ["attack.execution", "attack.t1059.001"],
  "enabled": true,
  "stats": {
    "evaluations_last_24h": 8500,
    "matches_last_24h": 3,
    "true_positives_last_7d": 12,
    "false_positives_last_7d": 2
  }
}

GET /detection/rules/{id}/matches

Get recent matches for a rule

Query params:

from, to: Time range
page, size: Pagination

Response:

{
  "rule_id": "fb843269-508c-4b76-8b8d-88679db22ce7",
  "matches": [
    {
      "match_id": "alert-123-456",
      "timestamp": "2026-02-20T10:15:30Z",
      "event": {
        "process_name": "powershell.exe",
        "command_line": "powershell.exe -enc SQBFAFgA...",
        "user": "DESKTOP-ABC\\john",
        "host": "DESKTOP-ABC"
      },
      "verdict": "true_positive",
      "reviewed_by": "analyst@example.com",
      "reviewed_at": "2026-02-20T10:20:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "size": 20,
    "total": 45
  }
}

PUT /detection/rules/{id}

Update a rule (enable/disable, modify definition)

POST /detection/rules/{id}/test

Test a rule against sample events

Request:

{
  "events": [
    {
      "process_name": "powershell.exe",
      "command_line": "powershell.exe -enc SQBFAFgA..."
    }
  ]
}

Response:

{
  "results": [
    {
      "event_index": 0,
      "matched": true,
      "matched_conditions": ["selection"]
    }
  ]
}

GET /detection/metrics

Get detection engine performance metrics

Response:

{
  "rules_loaded": 450,
  "rules_enabled": 420,
  "evaluations_per_second": 125.5,
  "avg_evaluation_time_ms": 8.2,
  "p99_evaluation_time_ms": 25.5,
  "top_alerting_rules": [
    {
      "rule_id": "...",
      "title": "Suspicious Process Creation",
      "alerts_last_24h": 45
    }
  ],
  "alerts_by_severity": {
    "critical": 12,
    "high": 85,
    "medium": 320,
    "low": 120
  },
  "alerts_by_tactic": {
    "execution": 120,
    "persistence": 45,
    "defense_evasion": 78
  }
}

4. System Health APIs

GET /health

Overall system health check

Response:

{
  "status": "healthy",
  "timestamp": "2026-02-20T10:30:00Z",
  "services": {
    "connector-service": {
      "status": "up",
      "replicas": 3,
      "healthy_replicas": 3
    },
    "normalizer-service": {
      "status": "up",
      "replicas": 5,
      "healthy_replicas": 5
    },
    "detection-service": {
      "status": "up",
      "replicas": 5,
      "healthy_replicas": 5
    },
    "enrichment-service": {
      "status": "up",
      "replicas": 3,
      "healthy_replicas": 3
    }
  }
}

5. Alert Management APIs

GET /alerts

List alerts

Query params:

severity: Filter by severity
status: open, investigating, resolved, false_positive
from, to: Time range
page, size: Pagination

Response:

{
  "alerts": [
    {
      "id": "alert-123-456",
      "rule_id": "fb843269-508c-4b76-8b8d-88679db22ce7",
      "rule_title": "Suspicious Encoded PowerShell Command",
      "severity": "high",
      "status": "open",
      "event": {
        "timestamp": "2026-02-20T10:15:30Z",
        "source": "endpoint",
        "host": "DESKTOP-ABC",
        "user": "john",
        "process": "powershell.exe",
        "command_line": "powershell.exe -enc ..."
      },
      "enrichment": {
        "user_context": {
          "department": "IT",
          "is_privileged": true
        },
        "asset_context": {
          "criticality": "high",
          "os": "Windows 11",
          "ip": "10.0.1.50"
        },
        "threat_intel": {
          "known_malicious": false,
          "reputation_score": 45
        }
      },
      "mitre": {
        "tactics": ["execution"],
        "techniques": ["T1059.001"]
      },
      "created_at": "2026-02-20T10:15:31Z",
      "updated_at": "2026-02-20T10:15:31Z"
    }
  ],
  "pagination": {
    "page": 1,
    "size": 50,
    "total": 856
  }
}

PUT /alerts/{id}

Update alert status

Request:

{
  "status": "investigating",
  "assignee": "analyst@example.com",
  "notes": "Investigating with user"
}

6. WebSocket API for Real-Time Updates

WS /ws/monitoring

WebSocket connection for real-time metrics updates

Authentication: JWT token in query param ?token=xxx

Message types:

Server push (every 5 seconds):

{
  "type": "metrics_update",
  "timestamp": "2026-02-20T10:30:00Z",
  "data": {
    "ingestion_rate": 125.5,
    "normalization_latency_p99": 45.0,
    "alerts_last_minute": 8,
    "queue_consumer_lag_total": 1250
  }
}

Server push (on event):

{
  "type": "connector_status_change",
  "timestamp": "2026-02-20T10:30:00Z",
  "data": {
    "connector_id": "550e8400-...",
    "old_status": "healthy",
    "new_status": "unhealthy",
    "message": "Connection timeout"
  }
}

{
  "type": "new_alert",
  "timestamp": "2026-02-20T10:30:00Z",
  "data": {
    "alert_id": "alert-123-456",
    "severity": "critical",
    "rule_title": "Mimikatz Detected",
    "host": "DC-01"
  }
}

Client subscription:

{
  "action": "subscribe",
  "topics": ["metrics", "connector_health", "alerts"]
}

7. Console Pages

Key Console Pages

Dashboard - Overview with real-time metrics
Connectors - Manage data source integrations
Detection Rules - Detection rule management
Alerts - Alert triage and investigation
Pipeline - Detailed pipeline metrics and health
System Health - Service status

8. Customer Portal Pages

The following pages are available in the tenant-facing portal:

Portal Home / SOC Overview
- Alert volume, active incidents, ingestion health, and detection trend widgets
Alerts & Triage
- Search/filter by severity, status, source, MITRE tactic, and time range
Timeline Search
- Full timeline search with structured query support
Assets & Exposure
- Per-asset activity timeline and linked detections
Connectors
- Tenant connector onboarding and health monitoring
Reports
- Scheduled compliance and executive reports (PDF/CSV exports)
Tenant Settings
- SSO, role mapping, retention policy, notification channels

Portal API Requirements

Tenant isolation

Every request resolves tenant_id from JWT and enforces tenant context before query execution.
Internal system identifiers are never exposed in API responses.

Performance SLOs

Alert list page: p95 < 2.0s for 30-day query window.
Timeline search page: p95 < 3.0s with paginated results.
Connector health page: refresh interval 30s with <1% stale reads.

Auditability

Log portal user actions for search queries, case updates, and connector changes.
Persist immutable audit trail entries for 1 year minimum.

9. Large Dataset API Behavior (Sorting/Search/Filter)

Query contract standards

sort: comma-separated allowlisted fields with direction (example: detected_at:desc,severity:desc)
cursor: opaque token for next page
limit: default 50, endpoint max enforced
q: keyword search with page-specific field scope
filters: structured JSON expression for advanced filtering endpoints

Backend requirements

All sorting/filtering/search operations execute server-side.
Unsupported sort/filter fields return 400 INVALID_QUERY_FIELD.
Include metadata in responses:
- took_ms
- total_estimate
- truncated (boolean)
- query_warnings (array)

Performance targets

API response time: < 200ms (p95)
WebSocket latency: < 100ms
Dashboard refresh rate: 5 seconds
Metrics retention: 90 days