Appearance
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/presetsResponse
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/integrationsRequest Body
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
name | string | Yes | — | Display name for the integration |
siem_preset | string | Yes | — | Preset ID (e.g., splunk, sentinel, custom) |
delivery_type | string | No | webhook | webhook or pull |
endpoint_url | string | No | — | Webhook endpoint URL (required for webhook delivery) |
auth_type | string | No | bearer | bearer, api_key_header, basic, or custom |
auth_value | string | No | — | Authentication credential |
format | string | No | json | Output format: json, cef, leef, splunk_hec, sentinel, ocsf |
event_filters | object | No | {} | Event filter configuration |
batch_size | integer | No | 100 | Events per batch (1–1000) |
flush_interval_seconds | integer | No | 5 | Max seconds between flushes (1–60) |
minimization_policy | string | No | standard | PII minimization: standard, aggressive, none |
custom_headers | object | No | {} | Additional HTTP headers |
custom_enrichment | object | No | {} | 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/integrationsResponse
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}/enableDisable Integration
Pause event delivery for an integration.
POST /api/admin/siem/integrations/{integration_id}/disableClone Integration
Create a copy of an existing integration with a new name.
POST /api/admin/siem/integrations/{integration_id}/cloneRequest 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}/testResponse
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-burstResponse
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}/previewQuery Parameters
| Parameter | Type | Description |
|---|---|---|
event_types | string | Comma-separated event types to preview |
format | string | Override 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/pullHeaders
Authorization: Bearer <pull_api_token>Query Parameters
| Parameter | Type | Description |
|---|---|---|
since | string | ISO 8601 timestamp — return events after this time |
cursor | string | Opaque cursor for pagination |
limit | integer | Max events to return (default: 100, max: 1000) |
format | string | Output format override |
integration_id | string | Filter 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}/backfillRequest 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/catalogResponse
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/categoriesResponse
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/detectionsResponse
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}/healthResponse
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/scoreResponse
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}/deliveriesQuery Parameters
| Parameter | Type | Description |
|---|---|---|
page | integer | Page number (default: 1) |
per_page | integer | Results per page (default: 50) |
Error Log
Get delivery errors with details.
GET /api/admin/siem/integrations/{integration_id}/errorsQuery Parameters
| Parameter | Type | Description |
|---|---|---|
since | string | ISO 8601 timestamp |
limit | integer | Max 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}/reconciliationQuery Parameters
| Parameter | Type | Description |
|---|---|---|
start | string | Start timestamp (ISO 8601) |
end | string | End 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}/gapsResponse
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-estimateResponse
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-credentialsRequest 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-tokenResponse
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/schemaResponse
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"
}
}| Field | Type | Description |
|---|---|---|
event_id | string | Unique event identifier |
event_type | string | Event type from the catalog (e.g., pii.detected) |
category | string | Event category |
timestamp | string | ISO 8601 with millisecond precision |
organization_id | string | Originating organization |
tenant_name | string | Organization display name |
severity | string | critical, high, medium, low, informational |
data | object | Event-specific payload (varies by event type) |
compliance_tags | string[] | Applicable regulations |
mitre_attack | string|null | MITRE ATT&CK technique ID |
event_hash | string | SHA-256 hash of this event |
prev_hash | string | SHA-256 hash of the previous event in the chain |
sequence_number | integer | Monotonically increasing per organization |
enrichment | object | Custom key-value pairs from integration config |
Error Responses
All endpoints return standard error responses:
json
{
"detail": "Integration not found"
}| Status | Description |
|---|---|
400 | Invalid request (e.g., invalid URL, invalid format) |
401 | Authentication required |
403 | Insufficient permissions (requires admin/owner role) |
404 | Resource not found or not owned by your organization |
429 | Rate limit exceeded |