Skip to content

SIEM Integration API ​

All SIEM endpoints require authentication and the admin or owner role in the organization.

Base path: /api/admin/siem

SIEM Presets ​

List Presets ​

List all available SIEM presets with summary information.

GET /api/admin/siem/presets

Response ​

json
[
  {
    "id": "splunk",
    "name": "Splunk",
    "logo": "splunk.svg",
    "format": "splunk_hec"
  },
  {
    "id": "sentinel",
    "name": "Microsoft Sentinel",
    "logo": "sentinel.svg",
    "format": "sentinel"
  }
]

Get Preset Details ​

Get full configuration details for a specific SIEM preset, including setup fields and guided steps.

GET /api/admin/siem/presets/{preset_id}

Response ​

json
{
  "id": "splunk",
  "name": "Splunk",
  "logo": "splunk.svg",
  "format": "splunk_hec",
  "auth_header": "Authorization",
  "auth_type": "bearer",
  "description": "Splunk Enterprise and Splunk Cloud via HTTP Event Collector",
  "setup_fields": [
    {
      "key": "endpoint_url",
      "label": "HEC Endpoint URL",
      "type": "url",
      "required": true,
      "placeholder": "https://your-splunk:8088/services/collector/event",
      "help": "The HTTP Event Collector endpoint URL"
    },
    {
      "key": "auth_value",
      "label": "HEC Token",
      "type": "password",
      "required": true,
      "help": "Your Splunk HEC authentication token"
    }
  ],
  "setup_steps": [
    "Create a new HEC token in Splunk Settings → Data Inputs → HTTP Event Collector",
    "Copy the token value and paste it below",
    "Enter your Splunk HEC endpoint URL"
  ]
}

Get Error Remediation ​

Get SIEM-specific troubleshooting advice for a given HTTP status code.

GET /api/admin/siem/presets/{preset_id}/error-remediation/{http_status}

Response ​

json
{
  "http_status": 403,
  "advice": "Verify that your HEC token has the 'Event' capability enabled and is assigned to the correct index."
}

Integration Management ​

Create Integration ​

Create a new SIEM integration for the authenticated user's organization.

POST /api/admin/siem/integrations

Request Body ​

FieldTypeRequiredDefaultDescription
namestringYes—Display name for the integration
siem_presetstringYes—Preset ID (e.g., splunk, sentinel, custom)
delivery_typestringNowebhookwebhook or pull
endpoint_urlstringNo—Webhook endpoint URL (required for webhook delivery)
auth_typestringNobearerbearer, api_key_header, basic, or custom
auth_valuestringNo—Authentication credential
formatstringNojsonOutput format: json, cef, leef, splunk_hec, sentinel, ocsf
event_filtersobjectNo{}Event filter configuration
batch_sizeintegerNo100Events per batch (1–1000)
flush_interval_secondsintegerNo5Max seconds between flushes (1–60)
minimization_policystringNostandardPII minimization: standard, aggressive, none
custom_headersobjectNo{}Additional HTTP headers
custom_enrichmentobjectNo{}Custom key-value pairs added to every event

Example ​

json
{
  "name": "Production Splunk",
  "siem_preset": "splunk",
  "delivery_type": "webhook",
  "endpoint_url": "https://splunk.example.com:8088/services/collector/event",
  "auth_type": "bearer",
  "auth_value": "your-hec-token",
  "format": "splunk_hec",
  "batch_size": 200,
  "flush_interval_seconds": 10,
  "minimization_policy": "standard"
}

Response ​

Returns the created integration object with auth_value masked.

List Integrations ​

List all SIEM integrations for the authenticated user's organization.

GET /api/admin/siem/integrations

Response ​

json
[
  {
    "id": "int_abc123",
    "organization_id": "org_xyz",
    "name": "Production Splunk",
    "siem_preset": "splunk",
    "delivery_type": "webhook",
    "endpoint_url": "https://splunk.example.com:8088/services/collector/event",
    "format": "splunk_hec",
    "enabled": true,
    "paused": false,
    "auth_value": "••••token",
    "batch_size": 200,
    "flush_interval_seconds": 10,
    "minimization_policy": "standard",
    "created_at": "2026-03-15T10:30:00Z"
  }
]

Get Integration ​

Get details for a specific integration.

GET /api/admin/siem/integrations/{integration_id}

Update Integration ​

Update configuration for an existing integration.

PATCH /api/admin/siem/integrations/{integration_id}

All fields from the create request are accepted; only provided fields are updated.

Delete Integration ​

Permanently delete an integration and its delivery history.

DELETE /api/admin/siem/integrations/{integration_id}

Response ​

json
{
  "status": "deleted"
}

Enable Integration ​

Enable event delivery for an integration.

POST /api/admin/siem/integrations/{integration_id}/enable

Disable Integration ​

Pause event delivery for an integration.

POST /api/admin/siem/integrations/{integration_id}/disable

Clone Integration ​

Create a copy of an existing integration with a new name.

POST /api/admin/siem/integrations/{integration_id}/clone

Request Body ​

json
{
  "name": "Splunk - Staging"
}

Testing & Validation ​

Send Test Event ​

Send a single test event to verify SIEM connectivity.

POST /api/admin/siem/integrations/{integration_id}/test

Response ​

json
{
  "status": "delivered",
  "http_status": 200,
  "latency_ms": 145,
  "event_type": "system.test_event"
}

Validation Burst ​

Send a burst of representative events covering multiple event types.

POST /api/admin/siem/integrations/{integration_id}/validation-burst

Response ​

json
{
  "events_sent": 12,
  "events_delivered": 12,
  "events_failed": 0,
  "results": [
    {
      "event_type": "auth.login",
      "status": "delivered",
      "http_status": 200
    },
    {
      "event_type": "pii.detected",
      "status": "delivered",
      "http_status": 200
    }
  ]
}

Preview Events ​

Preview how events look in the configured output format without sending them.

GET /api/admin/siem/integrations/{integration_id}/preview

Query Parameters ​

ParameterTypeDescription
event_typesstringComma-separated event types to preview
formatstringOverride output format for preview

Response ​

json
{
  "format": "splunk_hec",
  "events": [
    {
      "time": 1710500000,
      "sourcetype": "ghostai:security",
      "source": "ghostai",
      "event": {
        "event_type": "pii.detected",
        "severity": "medium",
        "entity_count": 3
      }
    }
  ]
}

Pull API ​

Poll Events ​

Authenticated endpoint for SIEMs that prefer pull-based ingestion.

GET /api/admin/siem/pull

Headers ​

Authorization: Bearer <pull_api_token>

Query Parameters ​

ParameterTypeDescription
sincestringISO 8601 timestamp — return events after this time
cursorstringOpaque cursor for pagination
limitintegerMax events to return (default: 100, max: 1000)
formatstringOutput format override
integration_idstringFilter to specific integration

Response ​

json
{
  "events": [
    {
      "event_id": "evt_abc123",
      "event_type": "pii.detected",
      "timestamp": "2026-03-15T10:30:00.123Z",
      "organization_id": "org_xyz",
      "severity": "medium",
      "data": { },
      "compliance_tags": ["HIPAA", "GDPR"],
      "event_hash": "sha256:...",
      "prev_hash": "sha256:...",
      "sequence_number": 42
    }
  ],
  "next_cursor": "cursor_abc",
  "has_more": true,
  "count": 100
}

Backfill ​

Replay Historical Events ​

Replay events from the audit log for a time range.

POST /api/admin/siem/integrations/{integration_id}/backfill

Request Body ​

json
{
  "start_timestamp": "2026-03-01T00:00:00Z",
  "end_timestamp": "2026-03-15T00:00:00Z"
}

Response ​

json
{
  "status": "started",
  "estimated_events": 15420,
  "time_range": {
    "start": "2026-03-01T00:00:00Z",
    "end": "2026-03-15T00:00:00Z"
  }
}

Event Catalog ​

List All Event Types ​

Browse the complete event catalog.

GET /api/admin/siem/catalog

Response ​

json
[
  {
    "event_type": "auth.login",
    "category": "authentication",
    "severity": "informational",
    "description": "User successfully authenticated",
    "compliance_tags": ["SOC2", "HIPAA"],
    "mitre_attack": "T1078"
  },
  {
    "event_type": "pii.detected",
    "category": "pii_detection",
    "severity": "medium",
    "description": "PII entities detected in user input",
    "compliance_tags": ["HIPAA", "GDPR", "PCI-DSS"],
    "mitre_attack": null
  }
]

Get Event Type Details ​

Get detailed information about a specific event type.

GET /api/admin/siem/catalog/{event_type}

Response ​

json
{
  "event_type": "pii.detected",
  "category": "pii_detection",
  "severity": "medium",
  "description": "PII entities detected in user input",
  "compliance_tags": ["HIPAA", "GDPR", "PCI-DSS"],
  "mitre_attack": null,
  "fields": {
    "entity_count": "integer — number of PII entities detected",
    "entity_types": "string[] — types of entities detected",
    "confidence_avg": "float — average detection confidence"
  }
}

List Event Categories ​

Get all event categories with event counts.

GET /api/admin/siem/catalog/categories

Response ​

json
[
  { "category": "authentication", "count": 12 },
  { "category": "pii_detection", "count": 8 },
  { "category": "file_processing", "count": 6 },
  { "category": "admin_actions", "count": 10 },
  { "category": "chat_model", "count": 5 },
  { "category": "policy_config", "count": 8 },
  { "category": "system", "count": 7 },
  { "category": "compliance", "count": 4 }
]

List Detection Rules ​

Get built-in detection rules for SIEM alerting.

GET /api/admin/siem/catalog/detections

Response ​

json
[
  {
    "rule_id": "ghostai_bulk_pii_exposure",
    "name": "Bulk PII Exposure",
    "description": "More than 100 PII entities detected in a 5-minute window",
    "severity": "critical",
    "event_types": ["pii.detected"],
    "condition": "entity_count_sum > 100 within 5m"
  }
]

Health Monitoring ​

Integration Health ​

Get health metrics for an integration.

GET /api/admin/siem/integrations/{integration_id}/health

Response ​

json
{
  "integration_id": "int_abc123",
  "success_rate": 99.7,
  "latency_p50_ms": 120,
  "latency_p95_ms": 340,
  "latency_p99_ms": 890,
  "events_delivered_24h": 15420,
  "errors_24h": 3,
  "last_success": "2026-03-15T10:29:55Z",
  "last_error": "2026-03-15T08:12:33Z",
  "last_error_status": 429
}

Health Score ​

Get the composite health score (0–100).

GET /api/admin/siem/integrations/{integration_id}/health/score

Response ​

json
{
  "score": 97,
  "factors": {
    "delivery_success_rate": 99.7,
    "avg_latency_ms": 145,
    "error_trend": "stable",
    "seconds_since_last_success": 65
  }
}

Delivery History ​

Get paginated delivery history.

GET /api/admin/siem/integrations/{integration_id}/deliveries

Query Parameters ​

ParameterTypeDescription
pageintegerPage number (default: 1)
per_pageintegerResults per page (default: 50)

Error Log ​

Get delivery errors with details.

GET /api/admin/siem/integrations/{integration_id}/errors

Query Parameters ​

ParameterTypeDescription
sincestringISO 8601 timestamp
limitintegerMax results (default: 50)

Response ​

json
{
  "errors": [
    {
      "timestamp": "2026-03-15T08:12:33Z",
      "http_status": 429,
      "error_message": "Rate limit exceeded",
      "batch_size": 200,
      "retry_count": 3,
      "remediation": "Increase batch size or flush interval to reduce request rate"
    }
  ]
}

Reconciliation ​

Compare delivered vs expected event counts.

GET /api/admin/siem/integrations/{integration_id}/reconciliation

Query Parameters ​

ParameterTypeDescription
startstringStart timestamp (ISO 8601)
endstringEnd timestamp (ISO 8601)

Response ​

json
{
  "expected_count": 15420,
  "delivered_count": 15417,
  "missing_count": 3,
  "duplicate_count": 0,
  "coverage_percent": 99.98
}

Gap Detection ​

Identify gaps in the event sequence.

GET /api/admin/siem/integrations/{integration_id}/gaps

Response ​

json
{
  "gaps": [
    {
      "start_sequence": 4201,
      "end_sequence": 4203,
      "missing_count": 2,
      "estimated_time": "2026-03-15T08:12:30Z"
    }
  ]
}

Volume Estimation ​

Estimate Event Volume ​

Estimate how many events per day your organization would generate.

GET /api/admin/siem/volume-estimate

Response ​

json
{
  "estimated_events_per_day": 12500,
  "breakdown": {
    "authentication": 800,
    "pii_detection": 5200,
    "file_processing": 1500,
    "admin_actions": 200,
    "chat_model": 3500,
    "policy_config": 50,
    "system": 1000,
    "compliance": 250
  },
  "estimated_bytes_per_day": 18750000
}

Credential Rotation ​

Rotate Webhook Credentials ​

Replace the webhook authentication credential without downtime.

POST /api/admin/siem/integrations/{integration_id}/rotate-credentials

Request Body ​

json
{
  "auth_value": "new-token-value"
}

Response ​

Returns the updated integration object.

Rotate Pull API Token ​

Generate a new HMAC token for the pull API, invalidating the previous token.

POST /api/admin/siem/integrations/{integration_id}/rotate-pull-token

Response ​

json
{
  "pull_token": "hmac_new_token_value",
  "expires_at": null,
  "previous_token_invalidated": true
}

Content Packs ​

Download Content Pack ​

Get SIEM-specific dashboards, saved searches, and detection rules.

GET /api/admin/siem/content-packs/{preset_id}

Response ​

json
{
  "preset_id": "splunk",
  "siem_name": "Splunk",
  "dashboards": [
    {
      "name": "GhostAI Security Overview",
      "description": "PII detection trends, auth events, and compliance score",
      "format": "splunk_xml",
      "content": "..."
    }
  ],
  "saved_searches": [
    {
      "name": "Failed Auth Spike",
      "query": "sourcetype=ghostai:security event_type=auth.login_failed | stats count by src_ip | where count > 10",
      "description": "Detects brute force attempts"
    }
  ],
  "detection_rules": [
    {
      "name": "Bulk PII Exposure",
      "description": "Alerts when >100 PII entities detected in 5 minutes",
      "query": "sourcetype=ghostai:security event_type=pii.detected | stats sum(entity_count) as total by organization_id | where total > 100"
    }
  ]
}

Output Format Schemas ​

List Format Schemas ​

List all available output format schemas.

GET /api/admin/siem/schema

Response ​

json
[
  { "format": "json", "name": "JSON", "description": "GhostAI native JSON format" },
  { "format": "cef", "name": "CEF", "description": "Common Event Format (ArcSight)" },
  { "format": "leef", "name": "LEEF", "description": "Log Event Extended Format (QRadar)" },
  { "format": "splunk_hec", "name": "Splunk HEC", "description": "Splunk HTTP Event Collector" },
  { "format": "sentinel", "name": "Sentinel", "description": "Microsoft Sentinel format" },
  { "format": "ocsf", "name": "OCSF", "description": "Open Cybersecurity Schema Framework v1.1" }
]

Get Format Schema ​

Get detailed schema for a specific output format.

GET /api/admin/siem/schema/{format_name}

Response ​

json
{
  "format": "cef",
  "name": "CEF",
  "version": "0.1",
  "description": "Common Event Format compatible with ArcSight and CEF-consuming SIEMs",
  "sample": "CEF:0|GhostAI|SecureChat|1.0|pii.detected|PII Detected|5|src=10.0.0.1 suser=user_hash entity_count=3",
  "field_mapping": {
    "deviceVendor": "GhostAI",
    "deviceProduct": "SecureChat",
    "signatureId": "event_type",
    "name": "event description",
    "severity": "0-10 scale"
  }
}

Event Envelope Schema ​

All events share a common envelope structure:

json
{
  "event_id": "evt_abc123def456",
  "event_type": "pii.detected",
  "category": "pii_detection",
  "timestamp": "2026-03-15T10:30:00.123Z",
  "organization_id": "org_xyz789",
  "tenant_name": "Acme Corp",
  "severity": "medium",
  "data": {
    "entity_count": 3,
    "entity_types": ["PERSON", "EMAIL_ADDRESS", "US_SSN"],
    "confidence_avg": 0.92,
    "session_id": "sess_abc"
  },
  "compliance_tags": ["HIPAA", "GDPR"],
  "mitre_attack": null,
  "event_hash": "sha256:a1b2c3d4e5f6...",
  "prev_hash": "sha256:f6e5d4c3b2a1...",
  "sequence_number": 42,
  "enrichment": {
    "environment": "production"
  }
}
FieldTypeDescription
event_idstringUnique event identifier
event_typestringEvent type from the catalog (e.g., pii.detected)
categorystringEvent category
timestampstringISO 8601 with millisecond precision
organization_idstringOriginating organization
tenant_namestringOrganization display name
severitystringcritical, high, medium, low, informational
dataobjectEvent-specific payload (varies by event type)
compliance_tagsstring[]Applicable regulations
mitre_attackstring|nullMITRE ATT&CK technique ID
event_hashstringSHA-256 hash of this event
prev_hashstringSHA-256 hash of the previous event in the chain
sequence_numberintegerMonotonically increasing per organization
enrichmentobjectCustom key-value pairs from integration config

Error Responses ​

All endpoints return standard error responses:

json
{
  "detail": "Integration not found"
}
StatusDescription
400Invalid request (e.g., invalid URL, invalid format)
401Authentication required
403Insufficient permissions (requires admin/owner role)
404Resource not found or not owned by your organization
429Rate limit exceeded

SOC 2 Type II Certified | BAA Available | HIPAA-Ready