Skip to content

Insider Risk API ​

All endpoints require authentication via API key or session cookie. Requests are scoped to the authenticated user’s organization.

Base path: /api/insider-risk

IOC definitions ​

Create IOC rule ​

Creates a new indicator-of-compromise (IOC) definition.

POST /api/insider-risk/iocs

Authentication: Required.

Query parameters: None.

Request body (JSON)

FieldTypeRequiredConstraintsDescription
namestringYesMax 200 charactersDisplay name
descriptionstringNoMax 2000 charactersOptional description
ioc_typestringYes—One of: volume_spike, off_hours, geo_anomaly, data_exfil, access_pattern, custom
patternstringYes—JSON-encoded pattern definition
severitystringNoDefault mediumOne of: low, medium, high, critical
enabledbooleanNoDefault trueWhether the rule is active
alert_channelsstring[]NoDefault ["webhook"]Channels: webhook (SIEM event), email
metadataobjectNo—Optional metadata; e.g. {"notification_emails": ["security@acme.com"]}

Response: 201 Created with an IOCResponse object.

IOCResponse ​

FieldTypeDescription
idstringIOC definition ID
organization_idstringOwning organization
namestringName
descriptionstringDescription
ioc_typestringIOC type
patternstringPattern JSON
severitystringSeverity
enabledbooleanEnabled flag
alert_channelsstring[]Alert channels
metadataobjectMetadata
created_bystringUser ID of creator
created_atstringISO 8601 timestamp
updated_atstringISO 8601 timestamp

Example ​

bash
curl -X POST "$BASE_URL/api/insider-risk/iocs" \
  -H "Authorization: Bearer $GHOSTAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Off-hours volume",
    "description": "Alert on unusual after-hours activity",
    "ioc_type": "off_hours",
    "pattern": "{\"window_utc\": [22, 6]}",
    "severity": "high",
    "enabled": true,
    "alert_channels": ["webhook", "email"],
    "metadata": {"notification_emails": ["security@acme.com"]}
  }'

List IOC rules ​

Lists IOC definitions for the organization.

GET /api/insider-risk/iocs

Authentication: Required.

Query parameters

ParameterTypeRequiredDescription
ioc_typestringNoFilter by IOC type
enabled_onlybooleanNoIf true, only enabled rules

Response: JSON array of IOCResponse.

Update IOC rule ​

Partially updates an IOC definition. Only supplied fields are changed.

PUT /api/insider-risk/iocs/{ioc_id}

Authentication: Required.

Query parameters: None.

Request body (JSON): all fields optional.

FieldTypeDescription
namestringMax 200 characters
descriptionstringMax 2000 characters
patternstringJSON-encoded pattern
severitystringlow, medium, high, critical
enabledbooleanEnabled flag
alert_channelsstring[]Alert channels
metadataobjectMetadata

Response: 200 OK with IOCResponse.

Delete IOC rule ​

DELETE /api/insider-risk/iocs/{ioc_id}

Authentication: Required.

Query parameters: None.

Request body: None.

Response: 204 No Content.

IOC match history ​

List matches ​

Returns IOC match events for the organization.

GET /api/insider-risk/ioc-matches

Authentication: Required.

Query parameters

ParameterTypeRequiredDefaultDescription
ioc_idstringNo—Filter by IOC definition ID
limitintegerNo50Page size, 1–500
unacknowledged_onlybooleanNo—Only unacknowledged matches

Response: JSON array of IOCMatchResponse.

FieldTypeDescription
idintegerMatch record ID
ioc_definition_idstringIOC definition ID
ioc_namestring | nullResolved IOC name
user_idstring | nullUser if applicable
session_idstring | nullSession if applicable
event_typestringEvent type
event_dataobjectEvent payload
matched_atstringISO 8601 timestamp
acknowledgedbooleanAcknowledgement state
acknowledged_bystring | nullUser who acknowledged
acknowledged_atstring | nullISO 8601 timestamp

Example ​

bash
curl -G "$BASE_URL/api/insider-risk/ioc-matches" \
  -H "Authorization: Bearer $GHOSTAI_API_KEY" \
  --data-urlencode "limit=100" \
  --data-urlencode "unacknowledged_only=true"

Acknowledge match ​

Marks a match as acknowledged.

POST /api/insider-risk/ioc-matches/{match_id}/acknowledge

Authentication: Required.

Query parameters: None.

Request body: None.

Response: 200 OK

json
{
  "status": "acknowledged",
  "match_id": 12345
}

Baselines ​

List baseline summaries ​

Returns one summary row per user that has baseline data.

GET /api/insider-risk/baselines

Authentication: Required.

Query parameters: None.

Request body: None.

Response: JSON array of BaselineSummary.

FieldTypeDescription
user_idstringUser ID
metrics_countintegerNumber of metrics
latest_periodstring | nullLatest period end (ISO 8601)
risk_scorenumberRisk score

Get user baseline detail ​

Returns detailed baseline metrics for a single user.

GET /api/insider-risk/baselines/{target_user_id}

Authentication: Required.

Path parameters

ParameterDescription
target_user_idUser whose baselines to load

Query parameters: None.

Request body: None.

Response: JSON array of BaselineResponse (up to 100 rows, ordered by period_end descending).

FieldTypeDescription
user_idstringUser ID
metric_typestringMetric type
metric_namestringMetric name
baseline_valuenumberBaseline value
stddevnumberStandard deviation
sample_countintegerSample count
period_startstringPeriod start (ISO 8601)
period_endstringPeriod end (ISO 8601)

Compute baselines (admin) ​

Computes user activity baselines from audit logs for the organization.

POST /api/insider-risk/baselines/compute

Authentication: Required (admin operation).

Query parameters

ParameterTypeRequiredDefaultDescription
period_daysintegerNo7Baseline period length in days, 1–30
lookback_daysintegerNo30Historical lookback in days, 7–90

Request body: None.

Response: 200 OK with BaselineComputeResponse.

FieldTypeDescription
organization_idstringOrganization ID
users_processedintegerUsers processed
metrics_writtenintegerMetrics written
errorsintegerError count
period_startstringPeriod start
period_endstringPeriod end

Example ​

bash
curl -X POST "$BASE_URL/api/insider-risk/baselines/compute?period_days=7&lookback_days=30" \
  -H "Authorization: Bearer $GHOSTAI_API_KEY"

Anomaly detection ​

Scan for anomalies (admin) ​

Runs anomaly detection against baselines and emits events to SIEM as configured.

POST /api/insider-risk/anomalies/scan

Authentication: Required (admin operation).

Query parameters

ParameterTypeRequiredDefaultDescription
warning_thresholdfloatNo2.5Warning deviation threshold, 1.0–5.0
critical_thresholdfloatNo3.5Critical deviation threshold, 2.0–10.0

Request body: None.

Response: 200 OK with AnomalyScanResponse.

FieldTypeDescription
anomalies_foundintegerCount detected
emitted_to_siemintegerEvents emitted to SIEM
anomaliesarrayList of AnomalyResponse

Each AnomalyResponse object:

FieldTypeDescription
idstringAnomaly ID
user_idstringUser ID
metric_typestringMetric type
metric_namestringMetric name
current_valuenumberObserved value
baseline_valuenumberBaseline
stddevnumberStandard deviation
deviationnumberDeviation score
severitystringSeverity
detected_atstringISO 8601 timestamp
detailsobjectAdditional details

List anomalies ​

Returns recent anomaly detections.

GET /api/insider-risk/anomalies

Authentication: Required.

Query parameters

ParameterTypeRequiredDefaultDescription
limitintegerNo50Max rows, 1–200

Request body: None.

Response: JSON array of AnomalyResponse.

Batch IOC evaluation (admin) ​

Evaluates IOC rules over a recent time window and persists matches.

POST /api/insider-risk/ioc-evaluate

Authentication: Required (admin operation).

Query parameters

ParameterTypeRequiredDefaultDescription
since_hoursintegerNo1Lookback window in hours, 1–24

Request body: None.

Response: 200 OK

json
{
  "matches_found": 0,
  "matches_persisted": 0,
  "alerts_dispatched": 0,
  "since": "2026-04-03T12:00:00+00:00"
}

Secret vault mappings ​

Create mapping ​

Registers where a hashed secret is stored in an external vault.

POST /api/insider-risk/vault-mappings

Authentication: Required.

Query parameters: None.

Request body (JSON)

FieldTypeRequiredDescription
secret_hashstringYesHash of the secret
vault_providerstringYeshashicorp_vault, aws_secrets_manager, or 1password
vault_pathstringYesPath or identifier in the vault

Response: 201 Created with SecretVaultMappingResponse.

FieldTypeDescription
idstringMapping ID
org_idstringOrganization ID
secret_hashstringSecret hash
vault_providerstringProvider
vault_pathstringVault path
created_atstringISO 8601 timestamp
last_usedstring | nullLast use time if tracked

List mappings ​

GET /api/insider-risk/vault-mappings

Authentication: Required.

Query parameters: None.

Request body: None.

Response: JSON array of SecretVaultMappingResponse.

Delete mapping ​

DELETE /api/insider-risk/vault-mappings/{mapping_id}

Authentication: Required.

Query parameters: None.

Request body: None.

Response: 204 No Content.

Event catalog ​

List event types ​

Returns audit event types for building access-pattern IOCs (same catalog semantics as the admin SIEM catalog, exposed here without the siem_integration feature flag).

GET /api/insider-risk/event-catalog

Authentication: Required.

Query parameters

ParameterTypeRequiredDescription
categorystringNoFilter by category

Request body: None.

Response: JSON array of objects:

FieldTypeDescription
event_typestringEvent type key
namestring | nullDisplay name
descriptionstring | nullDescription
categorystring | nullCategory
default_severitystring | nullDefault severity

TIP

The event catalog powers the IOC Access Pattern picker in the admin UI. It exposes the same data as GET /api/admin/siem/catalog without requiring the siem_integration feature flag.

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