dropzone openapi.yml
openapi: 3.0.3 info: title: Dropzone AI version: 0.1.0 description: AI SOC Analyst paths: /app/api/v1/chat/: post: operationId: chat_create description: | Send a chat query and receive an AI response.
This endpoint creates a new chat session if no session_id is provided,
or reuses an existing session to maintain conversation context.
Usage:
POST to this endpoint with your question
Receive session_id, message_id, and message_url in response
Poll the message_url or GET /app/api/v1/chat/{session_id}/message/{message_id} for results
(Optional) Include session_id query param in subsequent queries to maintain context
parameters: - in: query name: session_id schema: type: string description: 'Optional: UUID of existing chat session to maintain conversation context' tags: - chat requestBody: content: application/json: schema: type: object properties: text: type: string description: Your question or chat message files: type: array items: type: object properties: name: type: string description: File name (e.g., 'document.pdf') content: type: string description: Base64-encoded file content required: - name - content description: 'Optional: Files to include with your query. Each file must have ''name'' and ''content'' (base64-encoded) fields.' required: - text security: - ApiKeyAuth: [] responses: '201': content: application/json: schema: type: object properties: session_id: type: string format: uuid message_id: type: integer message_url: type: string description: Chat query created successfully. Use the message_url to poll for results. '400': content: application/json: schema: type: object properties: error_msg: type: string description: Bad request - invalid input '404': content: application/json: schema: type: object properties: error_msg: type: string description: Resource not found '401': content: application/json: schema: type: object properties: error_msg: type: string description: Unauthorized '403': content: application/json: schema: type: object properties: detail: type: string description: Access denied '500': content: application/json: schema: type: object properties: error_msg: type: string description: System error '503': content: application/json: schema: type: object properties: error_msg: type: string description: System not ready for requests /app/api/v1/chat/{session_id}/message/{message_id}: get: operationId: chat_message_retrieve description: | Get the status and result of a chat message.
Poll this endpoint after sending a query to check for completion.
Response fields:
response_text - AI response (null while processing)
response_citations - Supporting evidence/citations (null while processing)
progress_messages - Chronological list of processing status updates
(use the last entry for the current status while processing)
When both response_text and response_citations are populated, the query is complete.
parameters:
- in: path
name: message_id
schema:
type: integer
description: The message ID returned from POST /app/api/v1/chat/
required: true
- in: path
name: session_id
schema:
type: string
description: The chat session ID (UUID)
required: true
tags:
- chat
security:
- ApiKeyAuth: []
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/ChatQueryNested'
description: Chat message details with status and response (if complete)
'401':
content:
application/json:
schema:
type: object
properties:
error_msg:
type: string
description: Unauthorized
'403':
content:
application/json:
schema:
type: object
properties:
detail:
type: string
description: Access denied
'500':
content:
application/json:
schema:
type: object
properties:
error_msg:
type: string
description: System error
'503':
content:
application/json:
schema:
type: object
properties:
error_msg:
type: string
description: System not ready for requests
'400':
content:
application/json:
schema:
type: object
properties:
error_msg:
type: string
description: Bad request - invalid input
'404':
content:
application/json:
schema:
type: object
properties:
error_msg:
type: string
description: Resource not found
/app/api/v1/config/investigation-threshold:
get:
operationId: investigation_threshold_retrieve_external
description: Get investigation threshold configuration. The threshold controls
the maximum number of investigations allowed within a time window, with optional
per-alert-source limits.
tags:
- config
security:
- ApiKeyAuth: []
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/InvestigationThreshold'
description: Investigation threshold configuration
'401':
content:
application/json:
schema:
type: object
properties:
error_msg:
type: string
description: Unauthorized
'403':
content:
application/json:
schema:
type: object
properties:
detail:
type: string
description: Access denied
'500':
content:
application/json:
schema:
type: object
properties:
error_msg:
type: string
description: System error
'503':
content:
application/json:
schema:
type: object
properties:
error_msg:
type: string
description: System not ready for requests
patch:
operationId: investigation_threshold_update_external
description: 'Update investigation threshold configuration. Supports partial
updates. Fields: is_enabled (bool), max_invs (positive int), time_unit (hour|day|week|month),
max_by_alert_source (object mapping alert source labels to max counts).'
tags:
- config
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/PatchedInvestigationThreshold'
application/x-www-form-urlencoded:
schema:
$ref: '#/components/schemas/PatchedInvestigationThreshold'
multipart/form-data:
schema:
$ref: '#/components/schemas/PatchedInvestigationThreshold'
security:
- ApiKeyAuth: []
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/InvestigationThreshold'
description: Updated investigation threshold configuration
'400':
content:
application/json:
schema:
type: object
properties:
error_msg:
type: string
description: Bad request - invalid input
'401':
content:
application/json:
schema:
type: object
properties:
error_msg:
type: string
description: Unauthorized
'403':
content:
application/json:
schema:
type: object
properties:
detail:
type: string
description: Access denied
'500':
content:
application/json:
schema:
type: object
properties:
error_msg:
type: string
description: System error
'503':
content:
application/json:
schema:
type: object
properties:
error_msg:
type: string
description: System not ready for requests
/app/api/v1/config/investigation-threshold/status:
get:
operationId: config_investigation_threshold_status_retrieve
description: Get investigation threshold status including current progress toward
limits and counts of exceeded/queued investigations. Returns real-time usage
data for the current time window.
tags:
- config
security:
- ApiKeyAuth: []
responses:
'200':
content:
application/json:
schema:
type: object
properties:
progress:
type: object
nullable: true
description: Current progress toward threshold limits. null when
threshold is disabled (is_enabled=false).
properties:
time_unit:
type: string
enum:
- hour
- day
- week
- month
max_invs:
type: integer
minimum: 0
curr_invs:
type: integer
minimum: 0
by_alert_source:
type: object
description: 'Per-source progress. Valid keys: [''Check Point'',
''Check Point Harmony Email & Collaboration'', ''Gem'',
''Panther'', ''CrowdStrike'']...'
additionalProperties:
type: object
properties:
max_invs:
type: integer
minimum: 0
curr_invs:
type: integer
minimum: 0
example:
CrowdStrike:
max_invs: 50
curr_invs: 12
now:
type: string
format: date-time
start:
type: string
format: date-time
end:
type: string
format: date-time
example:
time_unit: day
max_invs: 100
curr_invs: 42
by_alert_source:
CrowdStrike:
max_invs: 50
curr_invs: 12
now: '2026-01-08T12:00:00Z'
start: '2026-01-08T00:00:00Z'
end: '2026-01-09T00:00:00Z'
exceeded:
type: integer
minimum: 0
queued:
type: integer
minimum: 0
example:
progress:
time_unit: day
max_invs: 100
curr_invs: 42
by_alert_source: {}
now: '2026-01-08T12:00:00Z'
start: '2026-01-08T00:00:00Z'
end: '2026-01-09T00:00:00Z'
exceeded: 3
queued: 5
description: Threshold status with progress and counts
'401':
content:
application/json:
schema:
type: object
properties:
error_msg:
type: string
description: Unauthorized
'403':
content:
application/json:
schema:
type: object
properties:
detail:
type: string
description: Access denied
'500':
content:
application/json:
schema:
type: object
properties:
error_msg:
type: string
description: System error
'503':
content:
application/json:
schema:
type: object
properties:
error_msg:
type: string
description: System not ready for requests
/app/api/v1/config/system:
get:
operationId: system_config_retrieve_external
description: 'Get all system configuration data. Returns current config values.
Sections: org_info, dashboard_defaults, response_benchmarks, time_saved, chatops,
advanced_settings'
tags:
- config
security:
- ApiKeyAuth: []
responses:
'200':
content:
application/json:
schema:
type: object
properties:
org_info:
type: object
title: Organization Info
properties:
company_name:
title: Organization Display Name
description: The name shown to users across the platform interface.
This is for visual branding only.
type: string
company_name_ai:
title: Official Company Name
description: Your registered organization name. Our AI uses
this during security investigations to identify your assets
and differentiate internal networks from external entities.
type: string
dashboard_defaults:
type: object
title: Dashboard Defaults
properties:
time_range:
title: Time Range
type: string
oneOf:
- const: last24hours
title: Last 24 hours
- const: last3days
title: Last 3 days
- const: last7days
title: Last 7 days
- const: last30days
title: Last 30 days
- const: last6months
title: Last 6 months
- const: last1year
title: Last 1 year
default: last30days
response_benchmarks:
type: object
title: Response Metric Benchmarks
description: These allow you to set performance targets reflecting
a human analyst's best effort—such as acknowledging alerts within
1 hour. This enables you to directly compare our AI SOC analyst
platform's speed with typical human response times for detection,
acknowledgment, investigation, and conclusion.
properties:
target1_ttd:
title: Industry Average TTD (minutes)
type: number
default: 10
target2_tta:
title: Industry Average TTA (minutes)
type: number
default: 60
target3_tti:
title: Industry Average TTI (minutes)
type: number
default: 30
target4_ttc:
title: Industry Average TTC (minutes)
type: number
default: 120
time_saved:
type: object
title: Value Metric Benchmarks
description: These are used as baselines in calculating dashboard
value metrics.
properties:
avg_min_per_inv:
title: Average minutes spent per manual investigation in your
environment
type: number
default: 25
avg_hours_per_week:
title: Average hours worked per week for one FTE analyst
type: number
default: 40
avg_cost_per_hour:
title: Average cost per hour for one FTE analyst
type: number
default: 60
chatops:
type: object
title: ChatOps Configuration
description: Configure Slack app secrets for ChatOps commands
and notifications.
properties:
slack_signing_secret:
title: Slack Signing Secret
description: The signing secret from your Slack app, used
to verify requests from Slack.
type: string
format: password
slack_token:
title: Slack Bot Token
description: The bot token from your Slack app, used for making
API calls to Slack (e.g., xoxb-...).
type: string
format: password
phishing_simulation_config:
type: object
title: Phishing Simulation Configuration
description: Settings for identifying and ignoring phishing simulation
emails.
properties:
phishing_simulation_domains:
title: Phishing Simulation Domains
description: Emails whose From-header domain or any body URL
domain matches (or is a subdomain of) one of these will
be marked IGNORED without investigation.
type: array
items:
type: string
uniqueItems: true
default: []
phishing_simulation_headers:
title: Phishing Simulation Headers
description: Emails containing any of these header names will
be marked IGNORED without investigation as phishing simulations.
Header names are matched case-insensitively.
type: array
items:
type: string
uniqueItems: true
default: []
advanced_settings:
type: object
title: Advanced Settings
properties:
enable_connector:
title: Enable Integration Connector
type: boolean
default: false
description: Enable for connecting to integrations behind
VPNs or firewalls.
enable_tenant_union:
title: Enable Multi-Tenant Map
type: boolean
default: false
description: Enable for vendor and/or dz-managed multi-tenant
integrations.
use_generated_alert_titles:
title: Display Generated Alert Titles
type: boolean
default: true
description: Enable to display Dropzone-generated alert titles,
otherwise display titles extracted from raw alert data.
enable_reinvestigate_btn:
title: Enable reinvestigation button
type: boolean
default: false
description: Allow users to re-run investigations for same
alert (counts against investigation quota)
advanced_alert_deduplication_settings:
title: Advanced Alert Deduplication Settings
type: object
properties:
enable_title_entity_deduplication:
title: Enable Title and Entity Deduplication
type: boolean
default: false
description: Enable to deduplicate alerts with identical
title and entity values within an 8 hour window.
allOf:
- if:
properties:
enable_title_entity_deduplication:
const: true
then:
properties:
title_entity_deduplication_settings:
title: Title and Entity Deduplication Settings
type: object
properties:
title_entity_deduplication_minimum_entity_count:
title: Minimum Entity Count
description: If an alert has fewer than this many
entities, it will not be considered for deduplication.
type: number
default: 3
minimum: 2
ui:order:
- org_info
- dashboard_defaults
- response_benchmarks
- time_saved
- chatops
- phishing_simulation_config
- advanced_settings
description: System configuration data
'401':
content:
application/json:
schema:
type: object
properties:
error_msg:
type: string
description: Unauthorized
'403':
content:
application/json:
schema:
type: object
properties:
detail:
type: string
description: Access denied
'500':
content:
application/json:
schema:
type: object
properties:
error_msg:
type: string
description: System error
'503':
content:
application/json:
schema:
type: object
properties:
error_msg:
type: string
description: System not ready for requests
put:
operationId: system_config_replace_external
description: Replace all system configuration data. Validates against JSON schema.
Must include all sections.
tags:
- config
requestBody:
content:
application/json:
schema:
type: object
properties:
org_info:
type: object
title: Organization Info
properties:
company_name:
title: Organization Display Name
description: The name shown to users across the platform interface.
This is for visual branding only.
type: string
company_name_ai:
title: Official Company Name
description: Your registered organization name. Our AI uses
this during security investigations to identify your assets
and differentiate internal networks from external entities.
type: string
dashboard_defaults:
type: object
title: Dashboard Defaults
properties:
time_range:
title: Time Range
type: string
oneOf:
- const: last24hours
title: Last 24 hours
- const: last3days
title: Last 3 days
- const: last7days
title: Last 7 days
- const: last30days
title: Last 30 days
- const: last6months
title: Last 6 months
- const: last1year
title: Last 1 year
default: last30days
response_benchmarks:
type: object
title: Response Metric Benchmarks
description: These allow you to set performance targets reflecting
a human analyst's best effort—such as acknowledging alerts within
1 hour. This enables you to directly compare our AI SOC analyst
platform's speed with typical human response times for detection,
acknowledgment, investigation, and conclusion.
properties:
target1_ttd:
title: Industry Average TTD (minutes)
type: number
default: 10
target2_tta:
title: Industry Average TTA (minutes)
type: number
default: 60
target3_tti:
title: Industry Average TTI (minutes)
type: number
default: 30
target4_ttc:
title: Industry Average TTC (minutes)
type: number
default: 120
time_saved:
type: object
title: Value Metric Benchmarks
description: These are used as baselines in calculating dashboard
value metrics.
properties:
avg_min_per_inv:
title: Average minutes spent per manual investigation in your
environment
type: number
default: 25
avg_hours_per_week:
title: Average hours worked per week for one FTE analyst
type: number
default: 40
avg_cost_per_hour:
title: Average cost per hour for one FTE analyst
type: number
default: 60
chatops:
type: object
title: ChatOps Configuration
description: Configure Slack app secrets for ChatOps commands and
notifications.
properties:
slack_signing_secret:
title: Slack Signing Secret
description: The signing secret from your Slack app, used to
verify requests from Slack.
type: string
format: password
slack_token:
title: Slack Bot Token
description: The bot token from your Slack app, used for making
API calls to Slack (e.g., xoxb-...).
type: string
format: password
phishing_simulation_config:
type: object
title: Phishing Simulation Configuration
description: Settings for identifying and ignoring phishing simulation
emails.
properties:
phishing_simulation_domains:
title: Phishing Simulation Domains
description: Emails whose From-header domain or any body URL
domain matches (or is a subdomain of) one of these will be
marked IGNORED without investigation.
type: array
items:
type: string
uniqueItems: true
default: []
phishing_simulation_headers:
title: Phishing Simulation Headers
description: Emails containing any of these header names will
be marked IGNORED without investigation as phishing simulations.
Header names are matched case-insensitively.
type: array
items:
type: string
uniqueItems: true
default: []
advanced_settings:
type: object
title: Advanced Settings
properties:
enable_connector:
title: Enable Integration Connector
type: boolean
default: false
description: Enable for connecting to integrations behind VPNs
or firewalls.
enable_tenant_union:
title: Enable Multi-Tenant Map
type: boolean
default: false
description: Enable for vendor and/or dz-managed multi-tenant
integrations.
use_generated_alert_titles:
title: Display Generated Alert Titles
type: boolean
default: true
description: Enable to display Dropzone-generated alert titles,
otherwise display titles extracted from raw alert data.
enable_reinvestigate_btn:
title: Enable reinvestigation button
type: boolean
default: false
description: Allow users to re-run investigations for same alert
(counts against investigation quota)
advanced_alert_deduplication_settings:
title: Advanced Alert Deduplication Settings
type: object
properties:
enable_title_entity_deduplication:
title: Enable Title and Entity Deduplication
type: boolean
default: false
description: Enable to deduplicate alerts with identical
title and entity values within an 8 hour window.
allOf:
- if:
properties:
enable_title_entity_deduplication:
const: true
then:
properties:
title_entity_deduplication_settings:
title: Title and Entity Deduplication Settings
type: object
properties:
title_entity_deduplication_minimum_entity_count:
title: Minimum Entity Count
description: If an alert has fewer than this many
entities, it will not be considered for deduplication.
type: number
default: 3
minimum: 2
ui:order:
- org_info
- dashboard_defaults
- response_benchmarks
- time_saved
- chatops
- phishing_simulation_config
- advanced_settings
security:
- ApiKeyAuth: []
responses:
'200':
content:
application/json:
schema:
type: object
properties:
org_info:
type: object
title: Organization Info
properties:
company_name:
title: Organization Display Name
description: The name shown to users across the platform interface.
This is for visual branding only.
type: string
company_name_ai:
title: Official Company Name
description: Your registered organization name. Our AI uses
this during security investigations to identify your assets
and differentiate internal networks from external entities.
type: string
dashboard_defaults:
type: object
title: Dashboard Defaults
properties:
time_range:
title: Time Range
type: string
oneOf:
- const: last24hours
title: Last 24 hours
- const: last3days
title: Last 3 days
- const: last7days
title: Last 7 days
- const: last30days
title: Last 30 days
- const: last6months
title: Last 6 months
- const: last1year
title: Last 1 year
default: last30days
response_benchmarks:
type: object
title: Response Metric Benchmarks
description: These allow you to set performance targets reflecting
a human analyst's best effort—such as acknowledging alerts within
1 hour. This enables you to directly compare our AI SOC analyst
platform's speed with typical human response times for detection,
acknowledgment, investigation, and conclusion.
properties:
target1_ttd:
title: Industry Average TTD (minutes)
type: number
default: 10
target2_tta:
title: Industry Average TTA (minutes)
type: number
default: 60
target3_tti:
title: Industry Average TTI (minutes)
type: number
default: 30
target4_ttc:
title: Industry Average TTC (minutes)
type: number
default: 120
time_saved:
type: object
title: Value Metric Benchmarks
description: These are used as baselines in calculating dashboard
value metrics.
properties:
avg_min_per_inv:
title: Average minutes spent per manual investigation in your
environment
type: number
default: 25
avg_hours_per_week:
title: Average hours worked per week for one FTE analyst
type: number
default: 40
avg_cost_per_hour:
title: Average cost per hour for one FTE analyst
type: number
default: 60
chatops:
type: object
title: ChatOps Configuration
description: Configure Slack app secrets for ChatOps commands
and notifications.
properties:
slack_signing_secret:
title: Slack Signing Secret
description: The signing secret from your Slack app, used
to verify requests from Slack.
type: string
format: password
slack_token:
title: Slack Bot Token
description: The bot token from your Slack app, used for making
API calls to Slack (e.g., xoxb-...).
type: string
format: password
phishing_simulation_config:
type: object
title: Phishing Simulation Configuration
description: Settings for identifying and ignoring phishing simulation
emails.
properties:
phishing_simulation_domains:
title: Phishing Simulation Domains
description: Emails whose From-header domain or any body URL
domain matches (or is a subdomain of) one of these will
be marked IGNORED without investigation.
type: array
items:
type: string
uniqueItems: true
default: []
phishing_simulation_headers:
title: Phishing Simulation Headers
description: Emails containing any of these header names will
be marked IGNORED without investigation as phishing simulations.
Header names are matched case-insensitively.
type: array
items:
type: string
uniqueItems: true
default: []
advanced_settings:
type: object
title: Advanced Settings
properties:
enable_connector:
title: Enable Integration Connector
type: boolean
default: false
description: Enable for connecting to integrations behind
VPNs or firewalls.
enable_tenant_union:
title: Enable Multi-Tenant Map
type: boolean
default: false
description: Enable for vendor and/or dz-managed multi-tenant
integrations.
use_generated_alert_titles:
title: Display Generated Alert Titles
type: boolean
default: true
description: Enable to display Dropzone-generated alert titles,
otherwise display titles extracted from raw alert data.
enable_reinvestigate_btn:
title: Enable reinvestigation button
type: boolean
default: false
description: Allow users to re-run investigations for same
alert (counts against investigation quota)
advanced_alert_deduplication_settings:
title: Advanced Alert Deduplication Settings
type: object
properties:
enable_title_entity_deduplication:
title: Enable Title and Entity Deduplication
type: boolean
default: false
description: Enable to deduplicate alerts with identical
title and entity values within an 8 hour window.
allOf:
- if:
properties:
enable_title_entity_deduplication:
const: true
then:
properties:
title_entity_deduplication_settings:
title: Title and Entity Deduplication Settings
type: object
properties:
title_entity_deduplication_minimum_entity_count:
title: Minimum Entity Count
description: If an alert has fewer than this many
entities, it will not be considered for deduplication.
type: number
default: 3
minimum: 2
ui:order:
- org_info
- dashboard_defaults
- response_benchmarks
- time_saved
- chatops
- phishing_simulation_config
- advanced_settings
description: Updated system configuration
'400':
content:
application/json:
schema:
type: object
properties:
error_msg:
type: string
description: Bad request - invalid input
'401':
content:
application/json:
schema:
type: object
properties:
error_msg:
type: string
description: Unauthorized
'403':
content:
application/json:
schema:
type: object
properties:
detail:
type: string
description: Access denied
'500':
content:
application/json:
schema:
type: object
properties:
error_msg:
type: string
description: System error
'503':
content:
application/json:
schema:
type: object
properties:
error_msg:
type: string
description: System not ready for requests
patch:
operationId: system_config_update_external
description: 'Partially update system configuration (deep merge with existing).
Send any subset of config. Example: {"advanced_settings": {"enable_connector":
true}}'
tags:
- config
requestBody:
content:
application/json:
schema:
type: object
properties:
org_info:
type: object
title: Organization Info
properties:
company_name:
title: Organization Display Name
description: The name shown to users across the platform interface.
This is for visual branding only.
type: string
company_name_ai:
title: Official Company Name
description: Your registered organization name. Our AI uses
this during security investigations to identify your assets
and differentiate internal networks from external entities.
type: string
dashboard_defaults:
type: object
title: Dashboard Defaults
properties:
time_range:
title: Time Range
type: string
oneOf:
- const: last24hours
title: Last 24 hours
- const: last3days
title: Last 3 days
- const: last7days
title: Last 7 days
- const: last30days
title: Last 30 days
- const: last6months
title: Last 6 months
- const: last1year
title: Last 1 year
default: last30days
response_benchmarks:
type: object
title: Response Metric Benchmarks
description: These allow you to set performance targets reflecting
a human analyst's best effort—such as acknowledging alerts within
1 hour. This enables you to directly compare our AI SOC analyst
platform's speed with typical human response times for detection,
acknowledgment, investigation, and conclusion.
properties:
target1_ttd:
title: Industry Average TTD (minutes)
type: number
default: 10
target2_tta:
title: Industry Average TTA (minutes)
type: number
default: 60
target3_tti:
title: Industry Average TTI (minutes)
type: number
default: 30
target4_ttc:
title: Industry Average TTC (minutes)
type: number
default: 120
time_saved:
type: object
title: Value Metric Benchmarks
description: These are used as baselines in calculating dashboard
value metrics.
properties:
avg_min_per_inv:
title: Average minutes spent per manual investigation in your
environment
type: number
default: 25
avg_hours_per_week:
title: Average hours worked per week for one FTE analyst
type: number
default: 40
avg_cost_per_hour:
title: Average cost per hour for one FTE analyst
type: number
default: 60
chatops:
type: object
title: ChatOps Configuration
description: Configure Slack app secrets for ChatOps commands and
notifications.
properties:
slack_signing_secret:
title: Slack Signing Secret
description: The signing secret from your Slack app, used to
verify requests from Slack.
type: string
format: password
slack_token:
title: Slack Bot Token
description: The bot token from your Slack app, used for making
API calls to Slack (e.g., xoxb-...).
type: string
format: password
phishing_simulation_config:
type: object
title: Phishing Simulation Configuration
description: Settings for identifying and ignoring phishing simulation
emails.
properties:
phishing_simulation_domains:
title: Phishing Simulation Domains
description: Emails whose From-header domain or any body URL
domain matches (or is a subdomain of) one of these will be
marked IGNORED without investigation.
type: array
items:
type: string
uniqueItems: true
default: []
phishing_simulation_headers:
title: Phishing Simulation Headers
description: Emails containing any of these header names will
be marked IGNORED without investigation as phishing simulations.
Header names are matched case-insensitively.
type: array
items:
type: string
uniqueItems: true
default: []
advanced_settings:
type: object
title: Advanced Settings
properties:
enable_connector:
title: Enable Integration Connector
type: boolean
default: false
description: Enable for connecting to integrations behind VPNs
or firewalls.
enable_tenant_union:
title: Enable Multi-Tenant Map
type: boolean
default: false
description: Enable for vendor and/or dz-managed multi-tenant
integrations.
use_generated_alert_titles:
title: Display Generated Alert Titles
type: boolean
default: true
description: Enable to display Dropzone-generated alert titles,
otherwise display titles extracted from raw alert data.
enable_reinvestigate_btn:
title: Enable reinvestigation button
type: boolean
default: false
description: Allow users to re-run investigations for same alert
(counts against investigation quota)
advanced_alert_deduplication_settings:
title: Advanced Alert Deduplication Settings
type: object
properties:
enable_title_entity_deduplication:
title: Enable Title and Entity Deduplication
type: boolean
default: false
description: Enable to deduplicate alerts with identical
title and entity values within an 8 hour window.
allOf:
- if:
properties:
enable_title_entity_deduplication:
const: true
then:
properties:
title_entity_deduplication_settings:
title: Title and Entity Deduplication Settings
type: object
properties:
title_entity_deduplication_minimum_entity_count:
title: Minimum Entity Count
description: If an alert has fewer than this many
entities, it will not be considered for deduplication.
type: number
default: 3
minimum: 2
ui:order:
- org_info
- dashboard_defaults
- response_benchmarks
- time_saved
- chatops
- phishing_simulation_config
- advanced_settings
security:
- ApiKeyAuth: []
responses:
'200':
content:
application/json:
schema:
type: object
properties:
org_info:
type: object
title: Organization Info
properties:
company_name:
title: Organization Display Name
description: The name shown to users across the platform interface.
This is for visual branding only.
type: string
company_name_ai:
title: Official Company Name
description: Your registered organization name. Our AI uses
this during security investigations to identify your assets
and differentiate internal networks from external entities.
type: string
dashboard_defaults:
type: object
title: Dashboard Defaults
properties:
time_range:
title: Time Range
type: string
oneOf:
- const: last24hours
title: Last 24 hours
- const: last3days
title: Last 3 days
- const: last7days
title: Last 7 days
- const: last30days
title: Last 30 days
- const: last6months
title: Last 6 months
- const: last1year
title: Last 1 year
default: last30days
response_benchmarks:
type: object
title: Response Metric Benchmarks
description: These allow you to set performance targets reflecting
a human analyst's best effort—such as acknowledging alerts within
1 hour. This enables you to directly compare our AI SOC analyst
platform's speed with typical human response times for detection,
acknowledgment, investigation, and conclusion.
properties:
target1_ttd:
title: Industry Average TTD (minutes)
type: number
default: 10
target2_tta:
title: Industry Average TTA (minutes)
type: number
default: 60
target3_tti:
title: Industry Average TTI (minutes)
type: number
default: 30
target4_ttc:
title: Industry Average TTC (minutes)
type: number
default: 120
time_saved:
type: object
title: Value Metric Benchmarks
description: These are used as baselines in calculating dashboard
value metrics.
properties:
avg_min_per_inv:
title: Average minutes spent per manual investigation in your
environment
type: number
default: 25
avg_hours_per_week:
title: Average hours worked per week for one FTE analyst
type: number
default: 40
avg_cost_per_hour:
title: Average cost per hour for one FTE analyst
type: number
default: 60
chatops:
type: object
title: ChatOps Configuration
description: Configure Slack app secrets for ChatOps commands
and notifications.
properties:
slack_signing_secret:
title: Slack Signing Secret
description: The signing secret from your Slack app, used
to verify requests from Slack.
type: string
format: password
slack_token:
title: Slack Bot Token
description: The bot token from your Slack app, used for making
API calls to Slack (e.g., xoxb-...).
type: string
format: password
phishing_simulation_config:
type: object
title: Phishing Simulation Configuration
description: Settings for identifying and ignoring phishing simulation
emails.
properties:
phishing_simulation_domains:
title: Phishing Simulation Domains
description: Emails whose From-header domain or any body URL
domain matches (or is a subdomain of) one of these will
be marked IGNORED without investigation.
type: array
items:
type: string
uniqueItems: true
default: []
phishing_simulation_headers:
title: Phishing Simulation Headers
description: Emails containing any of these header names will
be marked IGNORED without investigation as phishing simulations.
Header names are matched case-insensitively.
type: array
items:
type: string
uniqueItems: true
default: []
advanced_settings:
type: object
title: Advanced Settings
properties:
enable_connector:
title: Enable Integration Connector
type: boolean
default: false
description: Enable for connecting to integrations behind
VPNs or firewalls.
enable_tenant_union:
title: Enable Multi-Tenant Map
type: boolean
default: false
description: Enable for vendor and/or dz-managed multi-tenant
integrations.
use_generated_alert_titles:
title: Display Generated Alert Titles
type: boolean
default: true
description: Enable to display Dropzone-generated alert titles,
otherwise display titles extracted from raw alert data.
enable_reinvestigate_btn:
title: Enable reinvestigation button
type: boolean
default: false
description: Allow users to re-run investigations for same
alert (counts against investigation quota)
advanced_alert_deduplication_settings:
title: Advanced Alert Deduplication Settings
type: object
properties:
enable_title_entity_deduplication:
title: Enable Title and Entity Deduplication
type: boolean
default: false
description: Enable to deduplicate alerts with identical
title and entity values within an 8 hour window.
allOf:
- if:
properties:
enable_title_entity_deduplication:
const: true
then:
properties:
title_entity_deduplication_settings:
title: Title and Entity Deduplication Settings
type: object
properties:
title_entity_deduplication_minimum_entity_count:
title: Minimum Entity Count
description: If an alert has fewer than this many
entities, it will not be considered for deduplication.
type: number
default: 3
minimum: 2
ui:order:
- org_info
- dashboard_defaults
- response_benchmarks
- time_saved
- chatops
- phishing_simulation_config
- advanced_settings
description: Updated system configuration
'400':
content:
application/json:
schema:
type: object
properties:
error_msg:
type: string
description: Bad request - invalid input
'401':
content:
application/json:
schema:
type: object
properties:
error_msg:
type: string
description: Unauthorized
'403':
content:
application/json:
schema:
type: object
properties:
detail:
type: string
description: Access denied
'500':
content:
application/json:
schema:
type: object
properties:
error_msg:
type: string
description: System error
'503':
content:
application/json:
schema:
type: object
properties:
error_msg:
type: string
description: System not ready for requests
/app/api/v1/context-memory:
get:
operationId: context_memory_retrieve
description: |
List Context Memory Items with optional filtering, sorting, and pagination.
Returns active and/or archived user-created context memory entries accessible to this tenant. Use `limit` and `offset` for pagination. Supports filtering by source type, status, tenant union, and free-text search. parameters: - in: query name: limit schema: type: integer description: Number of results per page - in: query name: offset schema: type: integer description: Number of results to skip - in: query name: search_query schema: type: string description: Free-text search against item content - in: query name: sort_by schema: type: string enum: - id - updated_at - usage_count description: 'Sort field (default: `updated_at`)' - in: query name: sort_order schema: type: string enum: - asc - desc description: 'Sort direction (default: `desc`)' - in: query name: source_types schema: type: array items: type: string enum: - chat_message - config_form - integration_scrape - investigation_edit description: Filter by source type(s). Repeatable. - in: query name: status schema: type: string enum: - active - all - inactive description: 'Filter by archive status (default: `all`)' - in: query name: tags schema: type: array items: type: string description: Filter by tag(s). Returns items that have *any* of the specified tags. Repeatable. - in: query name: tenant_union_id schema: type: string description: Filter by tenant union. Pass an integer ID to scope to a specific union, or the string `null` to return only untenanted items. Omit to return all. tags: - context-memory security: - ApiKeyAuth: [] responses: '200': content: application/json: schema: $ref: '#/components/schemas/PaginatedContextMemoryList' description: Paginated list of Context Memory Items '400': content: application/json: schema: type: object properties: error_msg: type: string description: Bad request - invalid input '401': content: application/json: schema: type: object properties: error_msg: type: string description: Unauthorized '403': content: application/json: schema: type: object properties: detail: type: string description: Access denied '500': content: application/json: schema: type: object properties: error_msg: type: string description: System error '503': content: application/json: schema: type: object properties: error_msg: type: string description: System not ready for requests /app/api/v1/context-memory/{item_id}: get: operationId: context_memory_retrieve_2 description: Retrieve a single Context Memory Item by ID. parameters: - in: path name: item_id schema: type: integer description: ID of the Context Memory Item required: true tags: - context-memory security: - ApiKeyAuth: [] responses: '200': content: application/json: schema: $ref: '#/components/schemas/ContextMemoryItemToCustomer' description: Context Memory Item '400': content: application/json: schema: type: object properties: error_msg: type: string description: Bad request - invalid input '404': content: application/json: schema: type: object properties: error_msg: type: string description: Resource not found '401': content: application/json: schema: type: object properties: error_msg: type: string description: Unauthorized '403': content: application/json: schema: type: object properties: detail: type: string description: Access denied '500': content: application/json: schema: type: object properties: error_msg: type: string description: System error '503': content: application/json: schema: type: object properties: error_msg: type: string description: System not ready for requests /app/api/v1/context-memory/create: post: operationId: context_memory_create_create description: Create a new user Context Memory Item (+ optional tenant union OR tenant id/label). Prefer tenant_union_id for union-scoped context (multiple integration slots); tenant_id+tenant_label for upstream tenant scoping. tags: - context-memory requestBody: content: application/json: schema: type: object properties: content: type: string default: Hello world tenant_id: type: string default: null tenant_label: type: string default: null tenant_union_id: type: number default: null tags: type: array items: type: string maxLength: 64 maxItems: 20 description: Optional free-form organizational tags. default: [] security: - ApiKeyAuth: [] responses: '201': content: application/json: schema: type: object properties: item_id: type: number description: Context Memory Item created '400': content: application/json: schema: type: object properties: error_msg: type: string description: Bad request - invalid input '401': content: application/json: schema: type: object properties: error_msg: type: string description: Unauthorized '403': content: application/json: schema: type: object properties: detail: type: string description: Access denied '500': content: application/json: schema: type: object properties: error_msg: type: string description: System error '503': content: application/json: schema: type: object properties: error_msg: type: string description: System not ready for requests /app/api/v1/context-memory/delete/{item_id}: delete: operationId: context_memory_delete_destroy description: Delete an existing user Context Memory Item parameters: - in: path name: item_id schema: type: string required: true tags: - context-memory security: - ApiKeyAuth: [] responses: '200': content: application/json: schema: type: object properties: item_id: type: number description: Context Memory Item deleted '404': content: application/json: schema: type: object properties: error_msg: type: string description: Resource not found '401': content: application/json: schema: type: object properties: error_msg: type: string description: Unauthorized '403': content: application/json: schema: type: object properties: detail: type: string description: Access denied '500': content: application/json: schema: type: object properties: error_msg: type: string description: System error '503': content: application/json: schema: type: object properties: error_msg: type: string description: System not ready for requests /app/api/v1/context-memory/update/{item_id}: put: operationId: context_memory_update_update description: Update an existing user Context Memory Item (+ optional tenant union OR tenant id/label). Prefer tenant_union_id for union-scoped context (multiple integration slots); tenant_id+tenant_label for upstream tenant scoping. parameters: - in: path name: item_id schema: type: string required: true tags: - context-memory requestBody: content: application/json: schema: type: object properties: content: type: string default: Hello world tenant_id: type: string default: null tenant_label: type: string default: null tenant_union_id: type: number default: null tags: type: array items: type: string maxLength: 64 maxItems: 20 description: Optional free-form organizational tags. Omit to leave existing tags unchanged. default: [] security: - ApiKeyAuth: [] responses: '200': content: application/json: schema: type: object properties: item_id: type: number description: Context Memory Item updated '400': content: application/json: schema: type: object properties: error_msg: type: string description: Bad request - invalid input '404': content: application/json: schema: type: object properties: error_msg: type: string description: Resource not found '401': content: application/json: schema: type: object properties: error_msg: type: string description: Unauthorized '403': content: application/json: schema: type: object properties: detail: type: string description: Access denied '500': content: application/json: schema: type: object properties: error_msg: type: string description: System error '503': content: application/json: schema: type: object properties: error_msg: type: string description: System not ready for requests '409': content: application/json: schema: type: object properties: error_msg: type: string description: Invalid action taken on resource /app/api/v1/custom-strategies: get: operationId: custom_strategies_list_external description: List all custom strategies. Use is_protected filter to distinguish between user-created and OOTB strategies. parameters: - in: query name: alert_sources schema: type: array items: type: string description: Filter by alert sources - in: query name: attack_surfaces schema: type: array items: type: string description: Filter by attack surfaces - in: query name: is_archived schema: type: boolean description: Filter by archived status - in: query name: is_enabled schema: type: boolean description: Filter by enabled status - in: query name: is_protected schema: type: boolean description: Filter by protected status (true=OOTB, false=user-created) - in: query name: mitre_tactics schema: type: array items: type: string description: Filter by MITRE tactics - in: query name: search_query schema: type: string description: Search in strategy title and scenario tags: - custom-strategies security: - ApiKeyAuth: [] responses: '200': content: application/json: schema: type: array items: $ref: '#/components/schemas/FullCustomStrategy' description: List of custom strategies '401': content: application/json: schema: type: object properties: error_msg: type: string description: Unauthorized '403': content: application/json: schema: type: object properties: detail: type: string description: Access denied '500': content: application/json: schema: type: object properties: error_msg: type: string description: System error '503': content: application/json: schema: type: object properties: error_msg: type: string description: System not ready for requests post: operationId: custom_strategies_create_external description: Create a new custom strategy tags: - custom-strategies requestBody: content: application/json: schema: type: object properties: title: type: string is_enabled: type: boolean default: false attack_surfaces: type: array items: type: string mitre_tactics: type: array items: type: string alert_sources: type: array items: type: string scenario: type: string outcomes: type: array items: type: object instructions: type: array items: type: object priorities: type: array items: type: object required: - title security: - ApiKeyAuth: [] responses: '201': content: application/json: schema: $ref: '#/components/schemas/FullCustomStrategy' description: Custom strategy created successfully '400': content: application/json: schema: type: object properties: error_msg: type: string description: Bad request - invalid input '401': content: application/json: schema: type: object properties: error_msg: type: string description: Unauthorized '403': content: application/json: schema: type: object properties: detail: type: string description: Access denied '500': content: application/json: schema: type: object properties: error_msg: type: string description: System error '503': content: application/json: schema: type: object properties: error_msg: type: string description: System not ready for requests /app/api/v1/custom-strategies/{strategy_id}: get: operationId: custom_strategy_retrieve_external description: Get a specific custom strategy by ID. Includes both user-created and OOTB (protected) strategies. parameters: - in: path name: strategy_id schema: type: integer required: true tags: - custom-strategies security: - ApiKeyAuth: [] responses: '200': content: application/json: schema: $ref: '#/components/schemas/FullCustomStrategy' description: Custom strategy details '404': content: application/json: schema: type: object properties: error_msg: type: string description: Resource not found '401': content: application/json: schema: type: object properties: error_msg: type: string description: Unauthorized '403': content: application/json: schema: type: object properties: detail: type: string description: Access denied '500': content: application/json: schema: type: object properties: error_msg: type: string description: System error '503': content: application/json: schema: type: object properties: error_msg: type: string description: System not ready for requests put: operationId: custom_strategy_update_external description: Update a custom strategy (full replacement - creates new version) parameters: - in: path name: strategy_id schema: type: string required: true tags: - custom-strategies requestBody: content: application/json: schema: type: object properties: title: type: string is_enabled: type: boolean attack_surfaces: type: array items: type: string mitre_tactics: type: array items: type: string alert_sources: type: array items: type: string scenario: type: string outcomes: type: array items: type: object instructions: type: array items: type: object priorities: type: array items: type: object required: - title security: - ApiKeyAuth: [] responses: '200': content: application/json: schema: $ref: '#/components/schemas/FullCustomStrategy' description: Strategy updated successfully '400': content: application/json: schema: type: object properties: error_msg: type: string description: Bad request - invalid input '401': content: application/json: schema: type: object properties: error_msg: type: string description: Unauthorized '403': content: application/json: schema: type: object properties: detail: type: string description: Access denied '500': content: application/json: schema: type: object properties: error_msg: type: string description: System error '503': content: application/json: schema: type: object properties: error_msg: type: string description: System not ready for requests delete: operationId: custom_strategy_destroy_external description: Delete or archive a custom strategy (archives if referenced by investigations) parameters: - in: path name: strategy_id schema: type: string required: true tags: - custom-strategies security: - ApiKeyAuth: [] responses: '204': description: Strategy deleted or archived successfully '404': content: application/json: schema: type: object properties: error_msg: type: string description: Resource not found '401': content: application/json: schema: type: object properties: error_msg: type: string description: Unauthorized '403': content: application/json: schema: type: object properties: detail: type: string description: Access denied '500': content: application/json: schema: type: object properties: error_msg: type: string description: System error '503': content: application/json: schema: type: object properties: error_msg: type: string description: System not ready for requests '400': content: application/json: schema: type: object properties: error_msg: type: string description: Cannot delete already archived strategy /app/api/v1/email/investigation/create: post: operationId: email_investigation_create_create description: Creates a new email investigation, returning the ID. Optionally pass tenant_union_id (multi-tenant deployments) to scope the alert to a tenant union. tags: - email requestBody: content: multipart/form-data: schema: type: object properties: email: type: string format: binary tenant_union_id: type: integer nullable: true default: null origin_ticket_id: type: string nullable: true default: null origin_ticket_id_label: type: string nullable: true default: null origin_ticket_url: type: string nullable: true default: null security: - ApiKeyAuth: [] responses: '201': content: application/json: schema: type: object properties: id: type: number description: Creation success '400': content: application/json: schema: type: object properties: error_msg: type: string description: Bad request - invalid input '401': content: application/json: schema: type: object properties: error_msg: type: string description: Unauthorized '403': content: application/json: schema: type: object properties: detail: type: string description: Access denied '500': content: application/json: schema: type: object properties: error_msg: type: string description: System error '503': content: application/json: schema: type: object properties: error_msg: type: string description: System not ready for requests /app/api/v1/integrations: get: operationId: list_integration_types description: Returns all integration definitions (types) available in the system. Does not include instance-specific configuration. summary: List all available integration types parameters: - in: query name: categories schema: type: array items: type: string description: Filter by categories (can specify multiple, e.g., ?categories=siem&categories=edr) explode: true style: form - in: query name: dz_provided schema: type: boolean description: Filter by whether the integration type can be Dropzone-provided - in: query name: group schema: type: array items: type: string description: Filter by integration groups (can specify multiple, e.g., ?group=security&group=cloud) explode: true style: form - in: query name: integration_type schema: type: string enum: - core - interviewer - poller - remediator description: Filter by integration service type (core, interviewer, poller, remediator) tags: - integrations security: - ApiKeyAuth: [] responses: '200': content: application/json: schema: $ref: '#/components/schemas/IntegrationTypesListResponse' description: List of all available integration types/definitions '401': content: application/json: schema: type: object properties: error_msg: type: string description: Unauthorized '403': content: application/json: schema: type: object properties: detail: type: string description: Access denied '500': content: application/json: schema: type: object properties: error_msg: type: string description: System error '503': content: application/json: schema: type: object properties: error_msg: type: string description: System not ready for requests /app/api/v1/integrations/{slug}: get: operationId: integrations_retrieve description: List all configured instances for a specific integration. parameters: - in: path name: slug schema: type: string required: true - in: query name: tenant_union_id schema: type: integer description: Filter by tenant union ID tags: - integrations security: - ApiKeyAuth: [] responses: '200': content: application/json: schema: $ref: '#/components/schemas/IntegrationInstancesListResponse' description: List of integration instances (config_data NOT included) '404': content: application/json: schema: type: object properties: error_msg: type: string description: Resource not found '401': content: application/json: schema: type: object properties: error_msg: type: string description: Unauthorized '403': content: application/json: schema: type: object properties: detail: type: string description: Access denied '500': content: application/json: schema: type: object properties: error_msg: type: string description: System error '503': content: application/json: schema: type: object properties: error_msg: type: string description: System not ready for requests post: operationId: integrations_create description: Create a new integration instance. parameters: - in: path name: slug schema: type: string required: true tags: - integrations requestBody: content: application/json: schema: $ref: '#/components/schemas/IntegrationInstanceSerializerToCustomerCreate' application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/IntegrationInstanceSerializerToCustomerCreate' multipart/form-data: schema: $ref: '#/components/schemas/IntegrationInstanceSerializerToCustomerCreate' required: true security: - ApiKeyAuth: [] responses: '201': content: application/json: schema: $ref: '#/components/schemas/IntegrationSlotSerializerToCustomerFull' description: Successfully created integration instance '400': content: application/json: schema: type: object properties: error_msg: type: string description: Bad request - invalid input '404': content: application/json: schema: type: object properties: error_msg: type: string description: Resource not found '401': content: application/json: schema: type: object properties: error_msg: type: string description: Unauthorized '403': content: application/json: schema: type: object properties: detail: type: string description: Access denied '500': content: application/json: schema: type: object properties: error_msg: type: string description: System error '503': content: application/json: schema: type: object properties: error_msg: type: string description: System not ready for requests /app/api/v1/integrations/{slug}/{slot_uuid}: get: operationId: integrations_retrieve_2 description: Get specific integration instance with full config. parameters: - in: path name: slot_uuid schema: type: string format: uuid required: true - in: path name: slug schema: type: string required: true tags: - integrations security: - ApiKeyAuth: [] responses: '200': content: application/json: schema: $ref: '#/components/schemas/IntegrationSlotSerializerToCustomerFull' description: Full integration instance details including masked config_data '404': content: application/json: schema: type: object properties: error_msg: type: string description: Resource not found '401': content: application/json: schema: type: object properties: error_msg: type: string description: Unauthorized '403': content: application/json: schema: type: object properties: detail: type: string description: Access denied '500': content: application/json: schema: type: object properties: error_msg: type: string description: System error '503': content: application/json: schema: type: object properties: error_msg: type: string description: System not ready for requests patch: operationId: integrations_partial_update description: Update integration instance (partial update supported). parameters: - in: path name: slot_uuid schema: type: string format: uuid required: true - in: path name: slug schema: type: string required: true tags: - integrations requestBody: content: application/json: schema: $ref: '#/components/schemas/PatchedIntegrationInstanceSerializerToCustomerUpdate' application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/PatchedIntegrationInstanceSerializerToCustomerUpdate' multipart/form-data: schema: $ref: '#/components/schemas/PatchedIntegrationInstanceSerializerToCustomerUpdate' security: - ApiKeyAuth: [] responses: '200': content: application/json: schema: $ref: '#/components/schemas/IntegrationSlotSerializerToCustomerFull' description: Updated integration instance '400': content: application/json: schema: type: object properties: error_msg: type: string description: Bad request - invalid input '404': content: application/json: schema: type: object properties: error_msg: type: string description: Resource not found '401': content: application/json: schema: type: object properties: error_msg: type: string description: Unauthorized '403': content: application/json: schema: type: object properties: detail: type: string description: Access denied '500': content: application/json: schema: type: object properties: error_msg: type: string description: System error '503': content: application/json: schema: type: object properties: error_msg: type: string description: System not ready for requests delete: operationId: integrations_destroy description: Delete integration instance. parameters: - in: path name: slot_uuid schema: type: string format: uuid required: true - in: path name: slug schema: type: string required: true tags: - integrations security: - ApiKeyAuth: [] responses: '204': description: Integration instance deleted successfully '404': content: application/json: schema: type: object properties: error_msg: type: string description: Resource not found '401': content: application/json: schema: type: object properties: error_msg: type: string description: Unauthorized '403': content: application/json: schema: type: object properties: detail: type: string description: Access denied '500': content: application/json: schema: type: object properties: error_msg: type: string description: System error '503': content: application/json: schema: type: object properties: error_msg: type: string description: System not ready for requests /app/api/v1/integrations/{slug}/test: post: operationId: integrations_test_create description: Test integration configuration without saving it. Validates the config and tests connectivity. parameters: - in: path name: slug schema: type: string required: true tags: - integrations requestBody: content: application/json: schema: $ref: '#/components/schemas/IntegrationInstanceSerializerToCustomerTest' application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/IntegrationInstanceSerializerToCustomerTest' multipart/form-data: schema: $ref: '#/components/schemas/IntegrationInstanceSerializerToCustomerTest' required: true security: - ApiKeyAuth: [] responses: '200': description: Test successful - returns test results '400': content: application/json: schema: type: object properties: error_msg: type: string description: Bad request - invalid input '404': content: application/json: schema: type: object properties: error_msg: type: string description: Resource not found '401': content: application/json: schema: type: object properties: error_msg: type: string description: Unauthorized '403': content: application/json: schema: type: object properties: detail: type: string description: Access denied '500': content: application/json: schema: type: object properties: error_msg: type: string description: System error '503': content: application/json: schema: type: object properties: error_msg: type: string description: System not ready for requests /app/api/v1/investigation: get: operationId: investigation_retrieve description: | List investigations (with optional filtering, sorting, and search)
Returns a paginated list of investigations. By default, only completed investigations (state='success') are returned. Use query parameters to filter by state, outcomes, priorities, date ranges, and more. parameters: - in: query name: alert_create_from schema: type: string description: Filter by alert creation time (from). ISO 8601 format - in: query name: alert_create_until schema: type: string description: Filter by alert creation time (until). ISO 8601 format - in: query name: alert_start_from schema: type: string description: Filter by alert start time (from). ISO 8601 format (e.g., 2024-01-01 or 2024-01-01T00:00:00Z) - in: query name: alert_start_until schema: type: string description: Filter by alert start time (until). ISO 8601 format - in: query name: alert_tenants schema: type: array items: type: string description: Filter by alert tenant name (can be repeated) - in: query name: alert_types schema: type: array items: type: string description: Filter by alert type/handler key (can be repeated) - in: query name: attack_surfaces schema: type: array items: type: string enum: - Active Directory - Cloud Infrastructure - Endpoint - Identity - Kubernetes - Network - Phishing - SaaS description: Filter by attack surface (can be repeated) - in: query name: containment_action_statuses schema: type: array items: type: string enum: - disabled - failed - ready - running - success - undo_failed - undoing description: Filter by latest containment action run status per investigation (can be repeated) - in: query name: direct_source_labels schema: type: array items: type: string description: Filter by alert source label (can be repeated) - in: query name: feedback_updated_from schema: type: string description: Filter by feedback last updated time (from). ISO 8601 format - in: query name: feedback_updated_until schema: type: string description: Filter by feedback last updated time (until). ISO 8601 format - in: query name: insight_tag_names schema: type: array items: type: string description: Filter by insight tag name (can be repeated) - in: query name: interview_statuses schema: type: array items: type: string enum: - active - approved - canceled - declined - failed - finished - finished_with_referral - pending - timed_out description: Filter by interview status (can be repeated) - in: query name: inv_complete_from schema: type: string description: Filter by investigation completion time (from). ISO 8601 format - in: query name: inv_complete_until schema: type: string description: Filter by investigation completion time (until). ISO 8601 format - in: query name: investigation_state schema: type: string enum: - error - loading - not_asked - success description: 'Filter by investigation state. Valid values: not_asked (queued), loading (running), success (complete), error (stopped). Defaults to ''success''.' - in: query name: light schema: type: boolean default: false description: If true, returns a lightweight response with fewer fields (no alert, no findings) - in: query name: limit schema: type: integer description: Number of results per page - in: query name: mitre_tactics schema: type: array items: type: string enum: - Collection - Command and Control - Credential Access - Defense Evasion - Discovery - Execution - Exfiltration - Impact - Initial Access - Lateral Movement - Persistence - Privilege Escalation description: Filter by MITRE ATT&CK tactic (can be repeated) - in: query name: offset schema: type: integer description: Number of results to skip - in: query name: outcomes schema: type: array items: type: string enum: - COMPLETED_BREACHED_CONFIRMED - COMPLETED_BREACHED_SUSPICIOUS - COMPLETED_FALSE_ALERT - IGNORED - INCOMPLETE description: Filter by investigation outcome/conclusion (can be repeated) - in: query name: priorities schema: type: array items: type: string enum: - informational - notable - urgent description: Filter by investigation priority (can be repeated) - in: query name: priority_statuses schema: type: array items: type: string description: Filter by priority status (can be repeated) - in: query name: search schema: type: string description: Free-text search across investigation fields - in: query name: sort_dir schema: type: string enum: - asc - desc description: Sort direction. Defaults to 'desc'. - in: query name: sort_type schema: type: string enum: - activity - alert_create - alert_source - alert_title - alert_type - feedback_status - investigation_create - outcome - priority_status - stopped_reason description: Sort field. Defaults to 'alert_create'. - in: query name: stopped_reasons schema: type: array items: type: string enum: - CANCEL_MANUAL - CANCEL_THRESHOLD - ERROR description: Filter by stopped reason for error/canceled investigations (can be repeated) - in: query name: tenant_id schema: type: string description: Filter by tenant ID - in: query name: tenant_integration_key schema: type: string description: Filter by tenant integration key - in: query name: user_statuses schema: type: array items: type: string enum: - in_review - reviewed description: Filter by user feedback status (can be repeated) tags: - investigation security: - ApiKeyAuth: [] responses: '200': content: application/json: schema: $ref: '#/components/schemas/PaginatedInvestigationList' description: | Paginated list of investigations
Returns a paginated list of investigations. By default, only completed investigations (state='success') are returned. Use query parameters to filter by state, outcomes, priorities, date ranges, and more.
Use next and previous
URLs in the response for easy page navigation.
If light=true, returns a subset of fields (InvestigationLight schema).
'401':
content:
application/json:
schema:
type: object
properties:
error_msg:
type: string
description: Unauthorized
'403':
content:
application/json:
schema:
type: object
properties:
detail:
type: string
description: Access denied
'500':
content:
application/json:
schema:
type: object
properties:
error_msg:
type: string
description: System error
'503':
content:
application/json:
schema:
type: object
properties:
error_msg:
type: string
description: System not ready for requests
'400':
content:
application/json:
schema:
type: object
properties:
error_msg:
type: string
description: Bad request - invalid input
/app/api/v1/investigation-bulk-feedback:
patch:
operationId: investigation_bulk_feedback_partial_update
description: |
Bulk update investigation feedback
feedback.status options:
- In Review =
in_review - Reviewed =
reviewed
feedback.outcome options:
- Malicious =
COMPLETED_BREACHED_CONFIRMED - Suspicious =
COMPLETED_BREACHED_SUSPICIOUS - Benign =
COMPLETED_FALSE_ALERT - Inconclusive =
INCOMPLETE - Ignored =
IGNORED
feedback.priority options:
- Informational =
informational - Notable =
notable - Urgent =
urgent
tags:
- investigation-feedback
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/PatchedBulkInvestigationFeedbackRequest'
application/x-www-form-urlencoded:
schema:
$ref: '#/components/schemas/PatchedBulkInvestigationFeedbackRequest'
multipart/form-data:
schema:
$ref: '#/components/schemas/PatchedBulkInvestigationFeedbackRequest'
security:
- ApiKeyAuth: []
responses:
'200':
content:
application/json:
schema:
type: object
properties:
investigation_id:
type: number
description: Feedback updated
'400':
content:
application/json:
schema:
type: object
properties:
error_msg:
type: string
validation_error:
type: object
description: Field-level validation errors keyed by field name
description: Malformed request
'401':
content:
application/json:
schema:
type: object
properties:
error_msg:
type: string
description: Unauthorized
'403':
content:
application/json:
schema:
type: object
properties:
detail:
type: string
description: Access denied
'500':
content:
application/json:
schema:
type: object
properties:
error_msg:
type: string
description: System error
'503':
content:
application/json:
schema:
type: object
properties:
error_msg:
type: string
description: System not ready for requests
/app/api/v1/investigation-user-notes/{investigation_id}/create:
post:
operationId: investigation_user_notes_create_create
description: Add a new investigation note
parameters:
- in: path
name: investigation_id
schema:
type: integer
required: true
tags:
- investigation-user-notes
requestBody:
content:
application/json:
schema:
type: object
properties:
text:
type: string
security:
- ApiKeyAuth: []
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/InvestigationNoteNested'
description: New investigation note
'400':
content:
application/json:
schema:
type: object
properties:
error_msg:
type: string
description: Bad request - invalid input
'401':
content:
application/json:
schema:
type: object
properties:
error_msg:
type: string
description: Unauthorized
'403':
content:
application/json:
schema:
type: object
properties:
detail:
type: string
description: Access denied
'500':
content:
application/json:
schema:
type: object
properties:
error_msg:
type: string
description: System error
'503':
content:
application/json:
schema:
type: object
properties:
error_msg:
type: string
description: System not ready for requests
/app/api/v1/investigation-user-notes/{investigation_id}/list:
get:
operationId: investigation_user_notes_list_retrieve
description: List user notes for an investigation
parameters:
- in: path
name: investigation_id
schema:
type: integer
required: true
tags:
- investigation-user-notes
security:
- ApiKeyAuth: []
responses:
'200':
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/InvestigationNoteNested'
description: Investigation user notes
'400':
content:
application/json:
schema:
type: object
properties:
error_msg:
type: string
description: Bad request - invalid input
'401':
content:
application/json:
schema:
type: object
properties:
error_msg:
type: string
description: Unauthorized
'403':
content:
application/json:
schema:
type: object
properties:
detail:
type: string
description: Access denied
'500':
content:
application/json:
schema:
type: object
properties:
error_msg:
type: string
description: System error
'503':
content:
application/json:
schema:
type: object
properties:
error_msg:
type: string
description: System not ready for requests
/app/api/v1/investigation-user-notes/{investigation_note_id}/delete:
delete:
operationId: investigation_user_notes_delete_destroy
description: Delete an investigation note
parameters:
- in: path
name: investigation_note_id
schema:
type: integer
required: true
tags:
- investigation-user-notes
security:
- ApiKeyAuth: []
responses:
'200':
description: Delete success
'404':
content:
application/json:
schema:
type: object
properties:
error_msg:
type: string
description: Resource not found
'401':
content:
application/json:
schema:
type: object
properties:
error_msg:
type: string
description: Unauthorized
'403':
content:
application/json:
schema:
type: object
properties:
detail:
type: string
description: Access denied
'500':
content:
application/json:
schema:
type: object
properties:
error_msg:
type: string
description: System error
'503':
content:
application/json:
schema:
type: object
properties:
error_msg:
type: string
description: System not ready for requests
/app/api/v1/investigation-user-notes/{investigation_note_id}/update:
patch:
operationId: investigation_user_notes_update_partial_update
description: Update an investigation note
parameters:
- in: path
name: investigation_note_id
schema:
type: integer
required: true
tags:
- investigation-user-notes
requestBody:
content:
application/json:
schema:
type: object
properties:
text:
type: string
security:
- ApiKeyAuth: []
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/InvestigationNoteNested'
description: Updated investigation note
'400':
content:
application/json:
schema:
type: object
properties:
error_msg:
type: string
description: Bad request - invalid input
'401':
content:
application/json:
schema:
type: object
properties:
error_msg:
type: string
description: Unauthorized
'403':
content:
application/json:
schema:
type: object
properties:
detail:
type: string
description: Access denied
'500':
content:
application/json:
schema:
type: object
properties:
error_msg:
type: string
description: System error
'503':
content:
application/json:
schema:
type: object
properties:
error_msg:
type: string
description: System not ready for requests
/app/api/v1/investigation/{investigation_id}:
get:
operationId: investigation_retrieve_2
description: Returns an alert investigation
parameters:
- in: path
name: investigation_id
schema:
type: string
required: true
- in: query
name: light
schema:
type: boolean
default: false
description: If true, returns a lightweight response with fewer fields (no
alert, no findings)
tags:
- investigation
security:
- ApiKeyAuth: []
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/Investigation'
description: |
Investigation data object. For progress: investigation.status=
not_asked: queuedloading: running AI analystsuccess: AI analyst finished with resulterror: AI analyst finished with error — Seeinvestigation.error_msg
If light=true, returns a subset of fields (InvestigationLight schema).
'404':
content:
application/json:
schema:
type: object
properties:
error_msg:
type: string
description: Resource not found
'401':
content:
application/json:
schema:
type: object
properties:
error_msg:
type: string
description: Unauthorized
'403':
content:
application/json:
schema:
type: object
properties:
detail:
type: string
description: Access denied
'500':
content:
application/json:
schema:
type: object
properties:
error_msg:
type: string
description: System error
'503':
content:
application/json:
schema:
type: object
properties:
error_msg:
type: string
description: System not ready for requests
/app/api/v1/investigation/{investigation_id}/evidence-data/{evidence_data_id}:
get:
operationId: investigation_evidence_data_retrieve
description: |
Returns the requested evidence data for a specific investigation.
parameters:
- in: path
name: evidence_data_id
schema:
type: integer
description: The evidence data ID
required: true
- in: path
name: investigation_id
schema:
type: integer
description: The investigation ID
required: true
tags:
- investigation
security:
- ApiKeyAuth: []
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/EvidenceData'
description: Evidence data object
'400':
content:
application/json:
schema:
type: object
properties:
error_msg:
type: string
description: Bad request - invalid input
'404':
content:
application/json:
schema:
type: object
properties:
error_msg:
type: string
description: Resource not found
'401':
content:
application/json:
schema:
type: object
properties:
error_msg:
type: string
description: Unauthorized
'403':
content:
application/json:
schema:
type: object
properties:
detail:
type: string
description: Access denied
'500':
content:
application/json:
schema:
type: object
properties:
error_msg:
type: string
description: System error
'503':
content:
application/json:
schema:
type: object
properties:
error_msg:
type: string
description: System not ready for requests
/app/api/v1/investigation/{investigation_id}/feedback:
patch:
operationId: investigation_feedback_partial_update
description: |
Update feedback for a single investigation
feedback.status options:
- In Review =
in_review - Reviewed =
reviewed
feedback.outcome options:
feedback.priority options:
- Informational =
informational - Notable =
notable - Urgent =
urgent
parameters:
- in: path
name: investigation_id
schema:
type: integer
description: The investigation ID
required: true
tags:
- investigation-feedback
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/PatchedInvestigationFeedbackRequest'
application/x-www-form-urlencoded:
schema:
$ref: '#/components/schemas/PatchedInvestigationFeedbackRequest'
multipart/form-data:
schema:
$ref: '#/components/schemas/PatchedInvestigationFeedbackRequest'
security:
- ApiKeyAuth: []
responses:
'200':
content:
application/json:
schema:
type: object
description: The updated investigation feedback
description: Feedback updated
'400':
content:
application/json:
schema:
type: object
properties:
error_msg:
type: string
validation_error:
type: object
description: Field-level validation errors keyed by field name
description: Malformed request
'404':
content:
application/json:
schema:
type: object
properties:
error_msg:
type: string
description: Resource not found
'401':
content:
application/json:
schema:
type: object
properties:
error_msg:
type: string
description: Unauthorized
'403':
content:
application/json:
schema:
type: object
properties:
detail:
type: string
description: Access denied
'500':
content:
application/json:
schema:
type: object
properties:
error_msg:
type: string
description: System error
'503':
content:
application/json:
schema:
type: object
properties:
error_msg:
type: string
description: System not ready for requests
/app/api/v1/investigation/{investigation_id}/queue-priority:
post:
operationId: investigation_queue_priority_create
description: Set queue_priority for a queued investigation. Omit queue_priority
from the body (or pass null) to bump to top; pass 0 to return to default queue
order.
parameters:
- in: path
name: investigation_id
schema:
type: integer
description: The investigation ID
required: true
tags:
- investigation
requestBody:
content:
application/json:
schema:
type: object
properties:
queue_priority:
type: number
nullable: true
description: Priority value. Omit or null to bump to top (server
computes max + gap), 0 to return to default queue order.
security:
- ApiKeyAuth: []
responses:
'200':
content:
application/json:
schema:
type: object
properties:
id:
type: integer
description: The investigation ID
queue_priority:
type: number
description: The new queue_priority value
description: Priority updated
'400':
content:
application/json:
schema:
type: object
properties:
error_msg:
type: string
description: Bad request - invalid input
'404':
content:
application/json:
schema:
type: object
properties:
error_msg:
type: string
description: Resource not found
'401':
content:
application/json:
schema:
type: object
properties:
error_msg:
type: string
description: Unauthorized
'403':
content:
application/json:
schema:
type: object
properties:
detail:
type: string
description: Access denied
'500':
content:
application/json:
schema:
type: object
properties:
error_msg:
type: string
description: System error
'503':
content:
application/json:
schema:
type: object
properties:
error_msg:
type: string
description: System not ready for requests
/app/api/v1/investigation/create:
post:
operationId: investigation_create_create
description: |
Creates a new alert investigation, returning investigation_id
Returns existing id if alert already exists (unless force_reinvestigation=True)
Then: Use GET /app/api/v1/investigation/{investigation_id} for updates
tags:
- investigation
requestBody:
content:
application/json:
schema:
type: object
properties:
schema_key:
type: string
raw_alert_content:
type: object
force_reinvestigation:
type: boolean
default: false
tenant_union_id:
type: number
nullable: true
default: null
security:
- ApiKeyAuth: []
responses:
'200':
content:
application/json:
schema:
type: object
properties:
investigation_id:
type: number
description: Existing investigation found
'201':
content:
application/json:
schema:
type: object
properties:
investigation_id:
type: number
description: New investigation created
'400':
content:
application/json:
schema:
type: object
properties:
error_msg:
type: string
description: Bad request - invalid input
'401':
content:
application/json:
schema:
type: object
properties:
error_msg:
type: string
description: Unauthorized
'403':
content:
application/json:
schema:
type: object
properties:
detail:
type: string
description: Access denied
'500':
content:
application/json:
schema:
type: object
properties:
error_msg:
type: string
description: System error
'503':
content:
application/json:
schema:
type: object
properties:
error_msg:
type: string
description: System not ready for requests
'422':
content:
application/json:
schema:
type: object
properties:
error_msg:
type: string
skip_reason:
type: string
description: Alert skipped due to missing data (e.g., propagation delay)
/app/api/v1/investigation/create/custom:
post:
operationId: investigation_create_custom_create
description: |
Request body = arbitrary alert JSON to be parsed & investigated.
The system uses AI to extract metadata (title, timestamps, ticket info, etc.) from the alert JSON you provide.
You can optionally include a dz_metadata object to override or supplement the AI-extracted values.
Optional dz_metadata fields:
| Field | Type | Description |
|---|---|---|
title |
string | Override the AI-generated alert title |
alert_type |
string | Override the AI-detected alert type |
coalesce_key |
string | Key for grouping duplicate alerts (default: hash of alert content) |
create_time |
string (ISO 8601) | Alert creation timestamp (default: current time) |
start_time |
string (ISO 8601) | Alert start timestamp |
origin_ticket_id |
string | Ticket/alert ID from the originating system |
origin_ticket_url |
string | URL to the ticket/alert in the originating system |
force_investigate |
boolean | If true, bypass the "not a valid security alert" classification and investigate anyway |
Response = investigation_id if successful, error_msg otherwise
Returns existing id if alert already exists (unless ?force_reinvestigation=True)
Then: Use GET /app/api/v1/investigation/{investigation_id} for updates
parameters:
- in: query
name: force_reinvestigation
schema:
type: boolean
description: Force reinvestigation
- in: query
name: tenant_union_id
schema:
type: integer
description: Tenant union ID
tags:
- investigation
requestBody:
content:
application/json:
schema:
type: object
security:
- ApiKeyAuth: []
responses:
'200':
content:
application/json:
schema:
type: object
properties:
investigation_id:
type: number
description: Existing investigation found
'201':
content:
application/json:
schema:
type: object
properties:
investigation_id:
type: number
description: New investigation created
'400':
content:
application/json:
schema:
type: object
properties:
error_msg:
type: string
description: Bad request - invalid input
'401':
content:
application/json:
schema:
type: object
properties:
error_msg:
type: string
description: Unauthorized
'403':
content:
application/json:
schema:
type: object
properties:
detail:
type: string
description: Access denied
'500':
content:
application/json:
schema:
type: object
properties:
error_msg:
type: string
description: System error
'503':
content:
application/json:
schema:
type: object
properties:
error_msg:
type: string
description: System not ready for requests
'413':
content:
application/json:
schema:
type: object
properties:
error_msg:
type: string
skip_reason:
type: string
description: Content Too Large
/app/api/v1/metrics/mttx:
get:
operationId: metrics_mttx_retrieve
description: |
System-level MTTX metrics (MTTC, MTTD, MTTP, MTTI) with overall totals and per alert-source breakdowns.
Uses the same investigation filter query parameters as GET /app/api/v1/investigation.
parameters:
- in: query
name: alert_create_from
schema:
type: string
description: Filter by alert creation time (from). ISO 8601 format
- in: query
name: alert_create_until
schema:
type: string
description: Filter by alert creation time (until). ISO 8601 format
- in: query
name: alert_start_from
schema:
type: string
description: Filter by alert start time (from). ISO 8601 format (e.g., 2024-01-01
or 2024-01-01T00:00:00Z)
- in: query
name: alert_start_until
schema:
type: string
description: Filter by alert start time (until). ISO 8601 format
- in: query
name: alert_tenants
schema:
type: array
items:
type: string
description: Filter by alert tenant name (can be repeated)
- in: query
name: alert_types
schema:
type: array
items:
type: string
description: Filter by alert type/handler key (can be repeated)
- in: query
name: attack_surfaces
schema:
type: array
items:
type: string
enum:
- Active Directory
- Cloud Infrastructure
- Endpoint
- Identity
- Kubernetes
- Network
- Phishing
- SaaS
description: Filter by attack surface (can be repeated)
- in: query
name: containment_action_statuses
schema:
type: array
items:
type: string
enum:
- disabled
- failed
- ready
- running
- success
- undo_failed
- undoing
description: Filter by latest containment action run status per investigation
(can be repeated)
- in: query
name: direct_source_labels
schema:
type: array
items:
type: string
description: Filter by alert source label (can be repeated)
- in: query
name: feedback_updated_from
schema:
type: string
description: Filter by feedback last updated time (from). ISO 8601 format
- in: query
name: feedback_updated_until
schema:
type: string
description: Filter by feedback last updated time (until). ISO 8601 format
- in: query
name: insight_tag_names
schema:
type: array
items:
type: string
description: Filter by insight tag name (can be repeated)
- in: query
name: interview_statuses
schema:
type: array
items:
type: string
enum:
- active
- approved
- canceled
- declined
- failed
- finished
- finished_with_referral
- pending
- timed_out
description: Filter by interview status (can be repeated)
- in: query
name: inv_complete_from
schema:
type: string
description: Filter by investigation completion time (from). ISO 8601 format
- in: query
name: inv_complete_until
schema:
type: string
description: Filter by investigation completion time (until). ISO 8601 format
- in: query
name: mitre_tactics
schema:
type: array
items:
type: string
enum:
- Collection
- Command and Control
- Credential Access
- Defense Evasion
- Discovery
- Execution
- Exfiltration
- Impact
- Initial Access
- Lateral Movement
- Persistence
- Privilege Escalation
description: Filter by MITRE ATT&CK tactic (can be repeated)
- in: query
name: outcomes
schema:
type: array
items:
type: string
enum:
- COMPLETED_BREACHED_CONFIRMED
- COMPLETED_BREACHED_SUSPICIOUS
- COMPLETED_FALSE_ALERT
- IGNORED
- INCOMPLETE
description: Filter by investigation outcome/conclusion (can be repeated)
- in: query
name: priorities
schema:
type: array
items:
type: string
enum:
- informational
- notable
- urgent
description: Filter by investigation priority (can be repeated)
- in: query
name: priority_statuses
schema:
type: array
items:
type: string
description: Filter by priority status (can be repeated)
- in: query
name: search
schema:
type: string
description: Free-text search across investigation fields
- in: query
name: stopped_reasons
schema:
type: array
items:
type: string
enum:
- CANCEL_MANUAL
- CANCEL_THRESHOLD
- ERROR
description: Filter by stopped reason for error/canceled investigations (can
be repeated)
- in: query
name: tenant_id
schema:
type: string
description: Filter by tenant ID
- in: query
name: tenant_integration_key
schema:
type: string
description: Filter by tenant integration key
- in: query
name: user_statuses
schema:
type: array
items:
type: string
enum:
- in_review
- reviewed
description: Filter by user feedback status (can be repeated)
tags:
- metrics
security:
- ApiKeyAuth: []
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/MttxResponse'
description: MTTX aggregate metrics
'401':
content:
application/json:
schema:
type: object
properties:
error_msg:
type: string
description: Unauthorized
'403':
content:
application/json:
schema:
type: object
properties:
detail:
type: string
description: Access denied
'500':
content:
application/json:
schema:
type: object
properties:
error_msg:
type: string
description: System error
'503':
content:
application/json:
schema:
type: object
properties:
error_msg:
type: string
description: System not ready for requests
/app/api/v1/metrics/mttx/investigations:
get:
operationId: metrics_mttx_investigations_retrieve
description: |
Per-investigation MTTD, MTTP, and MTTI in seconds (float), keyed by investigation id.
**Collection Name:** If omitted and a file is provided, the filename (without extension) will be used. If no file is provided, collection_name is required.**Supported Formats:** - Single STIX JSON file (.json) - Compressed tar/zip archives (.tar.gz, .tgz, .zip) containing multiple STIX files
**Size Limits:** - File size: 100.0MB max tags: - Custom Threat Collections requestBody: content: multipart/form-data: schema: type: object properties: file: type: string format: binary description: STIX JSON file or compressed tar archive collection_name: type: string description: Collection name (optional, defaults to filename) example: My Threat Feed expires_at: type: string format: date-time nullable: true description: Optional. When set, internal threat intel search excludes this collection after this date. Omit or null for no expiry. security: - ApiKeyAuth: [] responses: '201': content: application/json: schema: $ref: '#/components/schemas/ImportResult' description: Successfully processed '400': content: application/json: schema: type: object properties: error_msg: type: string description: Bad request - missing file, invalid collection name, or invalid MIME type '409': content: application/json: schema: type: object properties: error_msg: type: string description: Conflict - duplicate file (already uploaded in last 5 minutes) or collection limit exceeded '413': content: application/json: schema: type: object properties: error_msg: type: string description: File too large - exceeds 100.0MB '507': content: application/json: schema: type: object properties: error_msg: type: string description: Insufficient storage space on server '401': content: application/json: schema: type: object properties: error_msg: type: string description: Unauthorized '403': content: application/json: schema: type: object properties: detail: type: string description: Access denied '500': content: application/json: schema: type: object properties: error_msg: type: string description: Internal server error - file processing failed or file save failed during async upload '503': content: application/json: schema: type: object properties: error_msg: type: string description: System not ready for requests /app/api/v1/threat-intel/collections/{collection_id}: get: operationId: threat_intel_retrieve_external description: Get details for a specific Custom Threat Collection. parameters: - in: path name: collection_id schema: type: string format: uuid required: true tags: - Custom Threat Collections security: - ApiKeyAuth: [] responses: '200': content: application/json: schema: $ref: '#/components/schemas/ThreatIntelCollection' description: 'Collection details. The file_info field is a dictionary keyed by filename. Each value is either a SingleFileInfo (for single files) or ArchiveFileInfo (for archives), determined by the ''type'' field. All file types include indicators_skipped count. ArchiveFileInfo includes detailed filename tracking: files_parsed (successfully parsed), files_errored (had errors), files_skipped (skipped entirely), and files_warning (partial success - imported some indicators but also had errors or skipped indicators).' '401': content: application/json: schema: type: object properties: error_msg: type: string description: Unauthorized '403': content: application/json: schema: type: object properties: detail: type: string description: Access denied '500': content: application/json: schema: type: object properties: error_msg: type: string description: System error '503': content: application/json: schema: type: object properties: error_msg: type: string description: System not ready for requests '404': content: application/json: schema: type: object properties: error_msg: type: string description: Resource not found patch: operationId: threat_intel_patch_external description: Update a Custom Threat Collection parameters: - in: path name: collection_id schema: type: string format: uuid required: true tags: - Custom Threat Collections requestBody: content: application/json: schema: $ref: '#/components/schemas/PatchedThreatIntelCollectionCoreSettings' application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/PatchedThreatIntelCollectionCoreSettings' multipart/form-data: schema: $ref: '#/components/schemas/PatchedThreatIntelCollectionCoreSettings' security: - ApiKeyAuth: [] responses: '200': content: application/json: schema: $ref: '#/components/schemas/ThreatIntelCollection' description: Updated collection '404': content: application/json: schema: type: object properties: error_msg: type: string description: Collection not found '401': content: application/json: schema: type: object properties: error_msg: type: string description: Unauthorized '403': content: application/json: schema: type: object properties: detail: type: string description: Access denied '500': content: application/json: schema: type: object properties: error_msg: type: string description: System error '503': content: application/json: schema: type: object properties: error_msg: type: string description: System not ready for requests delete: operationId: threat_intel_destroy_external description: Delete a Custom Threat Collection parameters: - in: path name: collection_id schema: type: string format: uuid required: true tags: - Custom Threat Collections security: - ApiKeyAuth: [] responses: '204': description: Collection deleted successfully '404': content: application/json: schema: type: object properties: error_msg: type: string description: Collection not found '401': content: application/json: schema: type: object properties: error_msg: type: string description: Unauthorized '403': content: application/json: schema: type: object properties: detail: type: string description: Access denied '500': content: application/json: schema: type: object properties: error_msg: type: string description: System error '503': content: application/json: schema: type: object properties: error_msg: type: string description: System not ready for requests /app/api/v1/threat-intel/collections/{collection_id}/files: put: operationId: threat_intel_files_replace_external description: | Replace all files in a Custom Threat Collection with a new STIX 2.x file or compressed archive.
This endpoint replaces all existing collection content with the uploaded data.
**Supported Formats:** - Single STIX JSON file (.json) - Compressed tar archives (.tar.gz, .tgz) containing multiple STIX files
**Size Limits:** - File size: 100.0MB max parameters: - in: path name: collection_id schema: type: string format: uuid required: true tags: - Custom Threat Collections requestBody: content: multipart/form-data: schema: type: object properties: file: type: string format: binary description: STIX JSON file or compressed tar archive required: - file security: - ApiKeyAuth: [] responses: '200': content: application/json: schema: $ref: '#/components/schemas/ImportResult' description: Successfully processed '400': content: application/json: schema: type: object properties: error_msg: type: string description: Bad request - missing file or invalid MIME type '404': content: application/json: schema: type: object properties: error_msg: type: string description: Collection not found '413': content: application/json: schema: type: object properties: error_msg: type: string description: File too large - exceeds 100.0MB '507': content: application/json: schema: type: object properties: error_msg: type: string description: Insufficient storage space on server '401': content: application/json: schema: type: object properties: error_msg: type: string description: Unauthorized '403': content: application/json: schema: type: object properties: detail: type: string description: Access denied '500': content: application/json: schema: type: object properties: error_msg: type: string description: Internal server error - file processing failed or file save failed during async upload '503': content: application/json: schema: type: object properties: error_msg: type: string description: System not ready for requests /app/api/v1/threat-intel/collections/bulk-delete: post: operationId: threat_intel_bulk_delete_external description: Bulk delete Custom Threat Collections. Skips non-existent and already-deleted collections. tags: - Custom Threat Collections requestBody: content: application/json: schema: $ref: '#/components/schemas/BulkDeleteCollectionsRequest' required: true security: - ApiKeyAuth: [] responses: '200': content: application/json: schema: $ref: '#/components/schemas/BulkDeleteCollectionsResponse' description: Bulk delete completed '400': content: application/json: schema: type: object properties: error_msg: type: string description: Bad request - missing or invalid collection_ids '401': content: application/json: schema: type: object properties: error_msg: type: string description: Unauthorized '403': content: application/json: schema: type: object properties: detail: type: string description: Access denied '500': content: application/json: schema: type: object properties: error_msg: type: string description: System error '503': content: application/json: schema: type: object properties: error_msg: type: string description: System not ready for requests components: schemas: BulkDeleteCollectionsRequest: type: object description: Request serializer for bulk delete collections endpoint. properties: collection_ids: type: array items: type: string format: uuid description: List of collection UUIDs to delete minItems: 1 required: - collection_ids BulkDeleteCollectionsResponse: type: object properties: deleted_count: type: integer description: Number of collections successfully deleted required: - deleted_count CanceledEnum: enum: - CANCEL_MANUAL - CANCEL_THRESHOLD type: string description: |- \* `CANCEL_MANUAL` - CANCEL_MANUAL \* `CANCEL_THRESHOLD` - CANCEL_THRESHOLD ChatQueryNested: type: object properties: id: type: integer readOnly: true request_user: $ref: '#/components/schemas/CustomUser' interview: $ref: '#/components/schemas/Interview' progress_messages: type: array items: $ref: '#/components/schemas/ChatQueryProgress' readOnly: true created_at: type: string format: date-time readOnly: true updated_at: type: string format: date-time readOnly: true request_text: type: string request_files: {} response_text: type: string nullable: true response_citations: nullable: true status: $ref: '#/components/schemas/ChatQueryNestedStatusEnum' chat_session: type: string format: uuid nullable: true required: - created_at - id - interview - progress_messages - request_text - request_user - updated_at ChatQueryNestedStatusEnum: enum: - pending - done - canceled type: string description: |- \* `pending` - Pending \* `done` - Done \* `canceled` - Canceled ChatQueryProgress: type: object properties: id: type: integer readOnly: true message: type: string timestamp: type: number format: double required: - id - message - timestamp ContextMemoryItemToCustomer: type: object description: |- Read-only serializer for customer-facing API endpoints. Exposes a safe subset of fields — no embeddings, source_data, or internal keys. tenant_union is a nested object. Write inputs use tenant_union_id (int) on create/update. properties: id: type: integer readOnly: true created_at: type: string format: date-time readOnly: true updated_at: type: string format: date-time readOnly: true expires_at: type: string format: date-time readOnly: true nullable: true is_archived: type: boolean readOnly: true content: type: string readOnly: true source_type: allOf: - $ref: '#/components/schemas/SourceTypeEnum' readOnly: true tenant_id: type: string readOnly: true nullable: true tenant_label: type: string readOnly: true nullable: true tenant_union: allOf: - $ref: '#/components/schemas/TenantUnion' readOnly: true nullable: true tags: type: array items: type: string readOnly: true required: - content - created_at - expires_at - id - is_archived - source_type - tags - tenant_id - tenant_label - tenant_union - updated_at CustomInstruction: type: object properties: id: type: integer usage_count: type: integer readOnly: true created_at: type: string format: date-time readOnly: true content: type: string internal_origin_uuid: type: string format: uuid readOnly: true nullable: true strategy_versions: type: array items: type: integer readOnly: true required: - content - created_at - internal_origin_uuid - strategy_versions - usage_count CustomOutcome: type: object properties: id: type: integer conclusions_affected: type: integer readOnly: true created_at: type: string format: date-time readOnly: true condition: {} outcome: $ref: '#/components/schemas/CustomOutcomeOutcomeEnum' internal_origin_uuid: type: string format: uuid readOnly: true nullable: true strategy_versions: type: array items: type: integer readOnly: true required: - conclusions_affected - condition - created_at - internal_origin_uuid - outcome - strategy_versions CustomOutcomeOutcomeEnum: enum: - COMPLETED_BREACHED_CONFIRMED - COMPLETED_BREACHED_SUSPICIOUS - COMPLETED_FALSE_ALERT - IGNORED type: string description: |- \* `COMPLETED_BREACHED_CONFIRMED` - COMPLETED_BREACHED_CONFIRMED \* `COMPLETED_BREACHED_SUSPICIOUS` - COMPLETED_BREACHED_SUSPICIOUS \* `COMPLETED_FALSE_ALERT` - COMPLETED_FALSE_ALERT \* `IGNORED` - IGNORED CustomPriority: type: object properties: id: type: integer priorities_affected: type: integer readOnly: true created_at: type: string format: date-time readOnly: true priority: $ref: '#/components/schemas/PriorityEnum' outcomes: type: array items: $ref: '#/components/schemas/OutcomesEnum' minItems: 1 insight_tag_rule: nullable: true ranking: type: integer maximum: 2147483647 minimum: 1 internal_origin_uuid: type: string format: uuid readOnly: true nullable: true strategy_versions: type: array items: type: integer readOnly: true required: - created_at - internal_origin_uuid - priorities_affected - priority - strategy_versions CustomUser: type: object description: |- Basic serializer to pass CustomUser details to the front end. Extend with any fields your app needs. properties: id: type: integer readOnly: true first_name: type: string maxLength: 150 last_name: type: string maxLength: 150 email: type: string format: email title: Email address maxLength: 254 role: $ref: '#/components/schemas/RoleEnum' oidc_user_id: type: string nullable: true required: - id EvidenceData: type: object properties: id: type: integer readOnly: true created_at: type: string format: date-time readOnly: true updated_at: type: string format: date-time readOnly: true data: type: string investigation: type: integer required: - created_at - data - id - investigation - updated_at FileTypeEnum: enum: - single_file - archive type: string description: |- \* `single_file` - single_file \* `archive` - archive FullCustomStrategy: type: object description: A serializer for a combined strategy and one of its versions. properties: id: type: integer readOnly: true internal_origin_uuid: type: string format: uuid readOnly: true created_at: type: string format: date-time readOnly: true updated_at: type: string format: date-time readOnly: true title: type: string readOnly: true rationale: type: string readOnly: true nullable: true toggle_guidance: type: string readOnly: true nullable: true is_enabled: type: boolean readOnly: true is_archived: type: boolean readOnly: true is_protected: type: boolean readOnly: true version_id: type: integer readOnly: true attack_surfaces: type: array items: type: string mitre_tactics: type: array items: type: string alert_sources: type: array items: type: string scenario: type: string nullable: true outcomes: type: array items: $ref: '#/components/schemas/CustomOutcome' readOnly: true instructions: type: array items: $ref: '#/components/schemas/CustomInstruction' readOnly: true priorities: type: array items: $ref: '#/components/schemas/CustomPriority' readOnly: true is_latest: type: boolean readOnly: true total_usage: type: integer nullable: true readOnly: true required: - created_at - id - instructions - internal_origin_uuid - is_archived - is_enabled - is_latest - is_protected - outcomes - priorities - rationale - title - toggle_guidance - total_usage - updated_at - version_id ImportResult: type: object description: Serializer for ImportResult dataclass from threat intelligence imports properties: file_type: nullable: true description: |- Type of file processed
\* `single_file` - single_file \* `archive` - archive oneOf: - $ref: '#/components/schemas/FileTypeEnum' - $ref: '#/components/schemas/NullEnum' collection_id: type: string nullable: true description: UUID of the collection collection_name: type: string nullable: true description: Name of the collection file_name: type: string nullable: true description: Name of the uploaded file file_hash: type: string nullable: true description: SHA-256 hash of the uploaded file files_processed: type: integer description: Number of files processed (0 for single files) files_succeeded: type: integer description: Number of files that succeeded (0 for single files) files_failed: type: integer description: Number of files that failed (0 for single files) files_parsed: type: array items: type: string description: List of filenames that were successfully parsed (empty for single files) files_errored: type: array items: type: string description: List of filenames that had errors (empty for single files) files_skipped: type: array items: type: object additionalProperties: {} description: List of skipped files with reasons. Each entry has 'filename' and 'reason' keys. (empty for single files) total_objects: type: integer description: Total STIX objects processed indicators: allOf: - $ref: '#/components/schemas/ObjectCounts' description: Indicator counts domain_objects: allOf: - $ref: '#/components/schemas/ObjectCounts' description: Domain object counts relationships: allOf: - $ref: '#/components/schemas/ObjectCounts' description: Relationship counts sightings: allOf: - $ref: '#/components/schemas/ObjectCounts' description: Sighting counts error_count: type: integer description: Total number of errors readOnly: true required: - domain_objects - error_count - files_errored - files_failed - files_parsed - files_processed - files_skipped - files_succeeded - indicators - relationships - sightings - total_objects IntegrationDefinitionSerializerToCustomer: type: object description: |- Serializer for integration definitions/types in customer API. Used for GET /api/v1/system/integration-definitions.
Returns the blueprint for each integration type including its configuration schema. Use this to discover what integrations are available and what config fields they require. properties: slug: type: string readOnly: true description: Unique slug for the integration (e.g., 'crowdstrike') display_name: type: string readOnly: true description: Human-readable integration name description: type: string readOnly: true nullable: true description: Description of the integration's capabilities docs_url: type: string readOnly: true nullable: true description: URL to integration documentation group: type: string readOnly: true description: 'Integration group: ''cloud'', ''prem'', or ''saas''' categories: type: array items: type: string readOnly: true description: Categories (e.g., ['EDR'], ['Identity']) config_schema: readOnly: true description: JSON Schema defining required and optional configuration fields for this integration connector_support: type: string readOnly: true description: 'Connector requirement: ''no_connector'', ''optional_connector'', or ''required_connector''' has_scanner: type: string readOnly: true description: 'Scanner capability: ''no_scan'', ''optional_scan'', or ''required_scan''' allows_multi_slot: type: boolean readOnly: true description: Whether multiple instances of this integration can be configured (e.g., multiple AWS accounts) dz_provided: type: boolean description: Whether this integration type can be Dropzone-provided (configured with Dropzone-managed keys) readOnly: true required: - allows_multi_slot - categories - config_schema - connector_support - description - display_name - docs_url - dz_provided - group - has_scanner - slug IntegrationInstanceSerializerToCustomerCreate: type: object description: |- Serializer for creating integration instances via customer API. Used for POST /api/v1/integrations/{slug}. properties: config_data: description: Configuration data matching the integration's config_schema. Include all required fields. tenant_union_id: type: integer nullable: true description: (Optional) Tenant union ID for multi-tenant integrations. Only use if you need separate integration configs per tenant union. connector_slug: type: string nullable: true description: (Optional) Connector slug for on-premises integrations requiring a connector. Only needed if the integration requires a connector. is_enabled: type: boolean default: true description: 'Whether to enable the integration immediately (default: true)' required: - config_data IntegrationInstanceSerializerToCustomerLight: type: object description: |- Lightweight serializer for listing integration instances in customer API. Does NOT include config_data - use GET /api/v1/integrations/{slug}/{uuid} for full details. properties: slug: type: string readOnly: true description: Unique slug for the integration type (e.g., 'crowdstrike', 'aws') display_name: type: string readOnly: true description: Human-readable name of the integration description: type: string readOnly: true nullable: true description: Description of the integration group: type: string readOnly: true nullable: true description: 'Integration group: ''cloud'', ''prem'', or ''saas''' categories: type: array items: type: string readOnly: true description: Categories this integration belongs to (e.g., ['EDR']) slot_uuid: type: string format: uuid readOnly: true description: Unique identifier for this specific instance tenant_union: allOf: - $ref: '#/components/schemas/TenantUnion' readOnly: true nullable: true description: Tenant union for this integration instance (if applicable) is_enabled: type: boolean readOnly: true description: Whether the integration is enabled status: type: string readOnly: true description: 'Connection status: ''connected'', ''disconnected'', ''error'', ''pending'', ''disabled'', or ''never_connected''' dz_provided: type: boolean readOnly: true description: Whether this is a Dropzone-provided integration (vs customer-configured) created_at: type: string format: date-time readOnly: true description: When this integration instance was created updated_at: type: string format: date-time readOnly: true description: When this integration instance was last updated required: - categories - created_at - description - display_name - dz_provided - group - is_enabled - slot_uuid - slug - status - tenant_union - updated_at IntegrationInstanceSerializerToCustomerTest: type: object description: |- Serializer for testing integration configuration via customer API. Used for POST /api/v1/integrations/{slug}/test. properties: config_data: description: Configuration data to test (does not modify the saved configuration) tenant_union_id: type: integer nullable: true description: (Optional) Tenant union ID to use for testing. Only use if testing multi-tenant integration configs. connector_slug: type: string nullable: true description: (Optional) Connector slug to use for testing. Only needed if testing integrations that require a connector. required: - config_data IntegrationInstancesListResponse: type: object properties: instances: type: array items: $ref: '#/components/schemas/IntegrationInstanceSerializerToCustomerLight' required: - instances IntegrationSlotSerializerToCustomerFull: type: object description: |- Full serializer for integration instances in customer API. Used for GET /api/v1/integrations/{slug}/{uuid} - includes config_data.
This returns complete details including configuration data (with passwords masked). For listing many instances without config, use GET /api/v1/integrations/{slug} instead. properties: slug: type: string readOnly: true description: Integration type slug (e.g., 'crowdstrike') display_name: type: string readOnly: true description: Human-readable integration name description: type: string readOnly: true nullable: true description: Integration description docs_url: type: string readOnly: true nullable: true description: URL to integration documentation group: type: string readOnly: true description: 'Integration group: ''cloud'', ''prem'', or ''saas''' categories: type: array items: type: string readOnly: true description: Categories (e.g., ['EDR']) config_schema: readOnly: true nullable: true description: JSON Schema for configuration fields - describes what config_data should contain connector_support: type: string readOnly: true description: Connector requirement level for this integration has_scanner: type: string readOnly: true description: Scanner capability level for this integration allows_multi_slot: type: boolean readOnly: true description: Whether multiple instances can be configured slot_uuid: type: string format: uuid readOnly: true description: Unique identifier for this specific instance tenant_union: allOf: - $ref: '#/components/schemas/TenantUnion' readOnly: true nullable: true description: Tenant union for this integration instance (if applicable) config_data: readOnly: true nullable: true description: Configuration data for this integration instance (passwords are masked with asterisks) is_enabled: type: boolean readOnly: true description: Whether the integration is enabled status: type: string readOnly: true description: 'Connection status: ''connected'', ''disconnected'', ''error'', ''pending'', etc.' dz_provided: type: boolean readOnly: true description: Whether this is a Dropzone-managed integration (vs customer-configured) created_at: type: string format: date-time readOnly: true description: When this integration instance was created updated_at: type: string format: date-time readOnly: true description: When this integration instance was last updated private_public_data: type: array items: type: object additionalProperties: {} nullable: true description: Dropzone-provided configuration data (ARNs, service account emails, etc.) that customers need but cannot modify readOnly: true required: - allows_multi_slot - categories - config_data - config_schema - connector_support - created_at - description - display_name - docs_url - dz_provided - group - has_scanner - is_enabled - private_public_data - slot_uuid - slug - status - tenant_union - updated_at IntegrationTypesListResponse: type: object properties: integrations: type: array items: $ref: '#/components/schemas/IntegrationDefinitionSerializerToCustomer' required: - integrations Interview: type: object properties: id: type: integer readOnly: true summary: type: string created_at: type: string format: date-time readOnly: true started_at: type: string format: date-time readOnly: true nullable: true updated_at: type: string format: date-time readOnly: true completed_at: type: string format: date-time nullable: true status: $ref: '#/components/schemas/InterviewStatusEnum' auto_approved: type: boolean interviewee_email: type: string question: type: string context: type: string nullable: true chat_history: {} error_msg: type: string nullable: true communicator: type: string nullable: true investigation: type: integer nullable: true required: - created_at - id - interviewee_email - question - started_at - summary - updated_at InterviewStatusEnum: enum: - pending - approved - active - finished - finished_with_referral - declined - failed - timed_out - canceled type: string description: |- \* `pending` - pending \* `approved` - approved \* `active` - active \* `finished` - finished \* `finished_with_referral` - finished_with_referral \* `declined` - declined \* `failed` - failed \* `timed_out` - timed_out \* `canceled` - canceled Investigation: oneOf: - $ref: '#/components/schemas/InvestigationFull' - $ref: '#/components/schemas/InvestigationLight' InvestigationFeedbackPatch: type: object description: |- Validates the `feedback` patch object accepted by the external feedback endpoints (single and bulk). Every field is optional so callers can patch any subset of the feedback. properties: status: $ref: '#/components/schemas/Status8faEnum' outcome: $ref: '#/components/schemas/Outcome4acEnum' priority: $ref: '#/components/schemas/PriorityEnum' outcome_note: type: string exclude_learning: type: boolean description: Set true to exclude from context memory generation InvestigationFull: type: object properties: id: type: integer readOnly: true inv_url: type: string readOnly: true created_at: type: string format: date-time readOnly: true updated_at: type: string format: date-time readOnly: true alert: $ref: '#/components/schemas/ScriptVarSerializer_Alert' start_time: type: string format: date-time nullable: true status: $ref: '#/components/schemas/StatusE6aEnum' canceled: nullable: true oneOf: - $ref: '#/components/schemas/CanceledEnum' - $ref: '#/components/schemas/NullEnum' error_msg: type: string nullable: true generated_time: type: string format: date-time nullable: true exec_summary: type: string nullable: true alert_summary: type: string nullable: true attack_surface: type: string nullable: true mitre_tactic: type: string nullable: true priority: nullable: true oneOf: - $ref: '#/components/schemas/PriorityEnum' - $ref: '#/components/schemas/NullEnum' outcome: nullable: true oneOf: - $ref: '#/components/schemas/Outcome982Enum' - $ref: '#/components/schemas/NullEnum' conclusion: type: string readOnly: true conclusion_summary: type: string nullable: true insight_tags: {} findings: {} key_findings: {} findings_ranking: {} recommended_remediations: {} related_alert_hypothesis: nullable: true interview_proposals: {} custom_outcome: type: object additionalProperties: {} nullable: true readOnly: true feedback: $ref: '#/components/schemas/ScriptVarSerializer_InvestigationFeedback' remediation_action_runs: type: array items: $ref: '#/components/schemas/ScriptVarSerializer_RemediationActionRun' readOnly: true ignored_for_investigation_id: type: integer nullable: true readOnly: true required: - alert - conclusion - created_at - custom_outcome - feedback - id - ignored_for_investigation_id - inv_url - remediation_action_runs - updated_at InvestigationLight: type: object description: |- A lightweight investigation serializer that only picks up certain fields.
Notably, we exclude: - no alert - no feedback - no findings
On the contrary, we *include* custom_outcome via annotation properties: id: type: integer readOnly: true status: $ref: '#/components/schemas/StatusE6aEnum' error_msg: type: string nullable: true alert_summary: type: string nullable: true attack_surface: type: string nullable: true mitre_tactic: type: string nullable: true priority: nullable: true oneOf: - $ref: '#/components/schemas/PriorityEnum' - $ref: '#/components/schemas/NullEnum' conclusion: type: string readOnly: true conclusion_summary: type: string nullable: true insight_tags: {} key_findings: {} recommended_remediations: {} inv_url: type: string readOnly: true custom_outcome: type: object additionalProperties: {} nullable: true readOnly: true detection_objective: type: string nullable: true required: - conclusion - custom_outcome - id - inv_url InvestigationNoteNested: type: object properties: id: type: integer readOnly: true user: $ref: '#/components/schemas/CustomUser' created_at: type: string format: date-time readOnly: true updated_at: type: string format: date-time readOnly: true text: type: string investigation: type: integer required: - created_at - id - investigation - updated_at - user InvestigationThreshold: type: object properties: id: type: integer readOnly: true max_invs: type: integer minimum: 0 description: Maximum investigations per time window (0 = block all) time_unit: allOf: - $ref: '#/components/schemas/TimeUnitEnum' description: |- Valid: ['hour', 'day', 'week', 'month']
\* `hour` - Hour
\* `day` - Day
\* `week` - Week
\* `month` - Month
max_by_alert_source:
type: object
description: 'Per-source limits (0 = block). Valid keys: [''Check Point'',
''Check Point Harmony Email & Collaboration'', ''Gem'', ''Panther'', ''CrowdStrike'']...'
additionalProperties:
type: integer
minimum: 0
example:
CrowdStrike: 50
created_at:
type: string
format: date-time
readOnly: true
updated_at:
type: string
format: date-time
readOnly: true
is_enabled:
type: boolean
last_exceeded_window_start:
readOnly: true
required:
- created_at
- id
- last_exceeded_window_start
- max_by_alert_source
- max_invs
- time_unit
- updated_at
MttxBreakdownStats:
type: object
description: Mean, median, p95 for one MTTX bucket (total or per source).
properties:
item_count:
type: integer
nullable: true
mean:
type: number
format: double
median:
type: number
format: double
p95:
type: number
format: double
required:
- mean
- median
- p95
MttxContainer:
type: object
description: Aggregate stats plus per alert-source breakdown.
properties:
total:
$ref: '#/components/schemas/MttxBreakdownStats'
by_source:
type: object
additionalProperties:
$ref: '#/components/schemas/MttxBreakdownStats'
description: Keyed by alert direct source label
required:
- by_source
- total
MttxPerInvestigationResponse:
type: object
description: Per-investigation MTTD, MTTP, MTTI in seconds (float), keyed by
investigation id.
properties:
mttd:
type: object
additionalProperties:
type: number
format: double
description: Investigation id (string key) to seconds
mttp:
type: object
additionalProperties:
type: number
format: double
description: Investigation id (string key) to seconds
mtti:
type: object
additionalProperties:
type: number
format: double
description: Investigation id (string key) to seconds
required:
- mttd
- mtti
- mttp
MttxResponse:
type: object
description: 'System-level MTTX: MTTC, MTTD, MTTP, MTTI with totals and by_source.'
properties:
mttc:
$ref: '#/components/schemas/MttxContainer'
mttd:
$ref: '#/components/schemas/MttxContainer'
mttp:
$ref: '#/components/schemas/MttxContainer'
mtti:
$ref: '#/components/schemas/MttxContainer'
required:
- mttc
- mttd
- mtti
- mttp
NullEnum:
enum:
- null
ObjectCounts:
type: object
description: Serializer for ObjectCounts dataclass
properties:
found:
type: integer
description: Number of objects found
created:
type: integer
description: Number of objects created
updated:
type: integer
description: Number of objects updated
skipped:
type: integer
description: Number of objects skipped
required:
- created
- found
- skipped
- updated
Outcome4acEnum:
enum:
- COMPLETED_BREACHED_CONFIRMED
- COMPLETED_BREACHED_SUSPICIOUS
- COMPLETED_FALSE_ALERT
- INCOMPLETE
- IGNORED
type: string
description: |-
\* `COMPLETED_BREACHED_CONFIRMED` - Malicious
\* `COMPLETED_BREACHED_SUSPICIOUS` - Suspicious
\* `COMPLETED_FALSE_ALERT` - Benign
\* `INCOMPLETE` - Inconclusive
\* `IGNORED` - Ignored
Outcome982Enum:
enum:
- COMPLETED_BREACHED_CONFIRMED
- COMPLETED_BREACHED_SUSPICIOUS
- COMPLETED_FALSE_ALERT
- INCOMPLETE
- IGNORED
type: string
description: |-
\* `COMPLETED_BREACHED_CONFIRMED` - COMPLETED_BREACHED_CONFIRMED
\* `COMPLETED_BREACHED_SUSPICIOUS` - COMPLETED_BREACHED_SUSPICIOUS
\* `COMPLETED_FALSE_ALERT` - COMPLETED_FALSE_ALERT
\* `INCOMPLETE` - INCOMPLETE
\* `IGNORED` - IGNORED
OutcomesEnum:
enum:
- COMPLETED_BREACHED_CONFIRMED
- COMPLETED_BREACHED_SUSPICIOUS
- COMPLETED_FALSE_ALERT
- INCOMPLETE
- IGNORED
type: string
description: |-
\* `COMPLETED_BREACHED_CONFIRMED` - COMPLETED_BREACHED_CONFIRMED
\* `COMPLETED_BREACHED_SUSPICIOUS` - COMPLETED_BREACHED_SUSPICIOUS
\* `COMPLETED_FALSE_ALERT` - COMPLETED_FALSE_ALERT
\* `INCOMPLETE` - INCOMPLETE
\* `IGNORED` - IGNORED
PaginatedContextMemoryList:
type: object
properties:
count:
type: integer
description: Total number of matching items
next:
type: string
format: uri
nullable: true
description: URL to next page
previous:
type: string
format: uri
nullable: true
description: URL to previous page
results:
type: array
items:
$ref: '#/components/schemas/ContextMemoryItemToCustomer'
required:
- count
- next
- previous
- results
PaginatedInvestigationList:
type: object
properties:
count:
type: integer
description: Total number of investigations
next:
type: string
format: uri
nullable: true
description: URL to next page of results
previous:
type: string
format: uri
nullable: true
description: URL to previous page of results
results:
type: array
items:
$ref: '#/components/schemas/Investigation'
required:
- count
- next
- previous
- results
PatchedBulkInvestigationFeedbackRequest:
type: object
description: Request body for updating feedback on multiple investigations at
once.
properties:
investigation_ids:
type: array
items:
type: integer
feedback:
$ref: '#/components/schemas/InvestigationFeedbackPatch'
PatchedIntegrationInstanceSerializerToCustomerUpdate:
type: object
description: |-
Serializer for updating integration instances via customer API.
Used for PATCH /api/v1/integrations/{slug}/{uuid}.
properties:
config_data:
description: New configuration data (must include all required fields from
config_schema)
tenant_union_id:
type: integer
nullable: true
description: (Optional) Update the tenant union for this integration. Only
use if you need separate integration configs per tenant union.
connector_slug:
type: string
nullable: true
description: (Optional) Update the connector for this integration. Only
needed if the integration requires a connector.
is_enabled:
type: boolean
description: Enable or disable the integration
PatchedInvestigationFeedbackRequest:
type: object
description: Request body for updating feedback on a single investigation.
properties:
feedback:
$ref: '#/components/schemas/InvestigationFeedbackPatch'
PatchedInvestigationThreshold:
type: object
properties:
id:
type: integer
readOnly: true
max_invs:
type: integer
minimum: 0
description: Maximum investigations per time window (0 = block all)
time_unit:
allOf:
- $ref: '#/components/schemas/TimeUnitEnum'
description: |-
Valid: ['hour', 'day', 'week', 'month']
\* `parsing` - Parsing \* `active` - Active \* `deleted` - Deleted \* `error` - Error created_at: type: string format: date-time readOnly: true updated_at: type: string format: date-time readOnly: true created_by: type: integer nullable: true description: User ID who created the collection. None indicates System user. readOnly: true updated_by: type: integer nullable: true description: User ID who last updated the collection. None indicates System user. readOnly: true file_info: type: object additionalProperties: type: object properties: type: type: string enum: - single_file - archive description: 'File type: ''single_file'' for individual JSON files, ''archive'' for ZIP/TAR archives' hash: type: string description: SHA-256 hash of the uploaded file or archive imported_at: type: string description: ISO 8601 timestamp when file was imported indicators_created: type: integer description: Number of indicators created from this file or archive indicators_updated: type: integer description: Number of indicators updated from this file or archive total_objects: type: integer description: Total STIX objects processed from this file or archive files_processed: type: integer description: Number of files processed from the archive (only present for archives) files_succeeded: type: integer description: Number of files that succeeded (only present for archives) files_failed: type: integer description: Number of files that failed (only present for archives) files_parsed: type: array items: type: string description: List of filenames that were successfully parsed (only present for archives) files_errored: type: array items: type: string description: List of filenames that had errors (only present for archives) files_skipped: type: array items: type: object properties: filename: type: string reason: type: string required: - filename - reason description: List of skipped files with reasons (only present for archives) required: - type - hash - imported_at - indicators_created - indicators_updated - total_objects example: threat_intel_bundle.json: type: single_file hash: a1b2c3d4e5f6789012345678901234567890abcdef1234567890abcdef123456 imported_at: '2024-01-15T10:30:00Z' indicators_created: 150 indicators_updated: 25 total_objects: 200 threat_feeds_archive.tar.gz: type: archive hash: b2c3d4e5f6789012345678901234567890abcdef1234567890abcdef1234567890 imported_at: '2024-01-15T10:30:00Z' files_processed: 10 files_succeeded: 8 files_failed: 1 files_parsed: - threat_feed_1.json - threat_feed_2.json - threat_feed_3.json - threat_feed_4.json - threat_feed_5.json - threat_feed_6.json - threat_feed_7.json - threat_feed_8.json files_errored: - invalid_file.json files_skipped: - filename: __MACOSX/.DS_Store reason: hidden_file - filename: readme.txt reason: not_json indicators_created: 500 indicators_updated: 100 total_objects: 750 description: Dictionary keyed by filename containing file metadata. Each entry contains common fields (type, hash, imported_at, indicators_created, indicators_updated, total_objects). Archive entries (type='archive') additionally include files_processed, files_succeeded, files_failed, files_parsed, files_errored, and files_skipped fields for detailed filename tracking. readOnly: true indicators_count: type: integer description: Get the count of indicators in this collection readOnly: true dz_owned: type: boolean readOnly: true default: false description: Flag to mark Dropzone-owned collections (e.g., auto-loaded threat intel) expires_at: type: string format: date-time readOnly: true nullable: true description: When set, internal threat intel search excludes this collection at and after this date. required: - created_at - created_by - dz_owned - expires_at - file_info - id - indicators_count - name - status - updated_at - updated_by ThreatIntelCollectionList: type: object properties: collections: type: array items: $ref: '#/components/schemas/ThreatIntelCollection' description: Array of collections count: type: integer description: Total number of collections returned required: - collections - count ThreatIntelCollectionStatusEnum: enum: - parsing - active - deleted - error type: string description: |- \* `parsing` - Parsing \* `active` - Active \* `deleted` - Deleted \* `error` - Error TimeUnitEnum: enum: - hour - day - week - month type: string description: |- \* `hour` - Hour \* `day` - Day \* `week` - Week \* `month` - Month securitySchemes: ApiKeyAuth: type: apiKey in: header name: Authorization