Skip to main content
POST
/
api
/
v2
/
workspaces
/
{workspaceId}
/
agent
/
tools
/
incidents
/
{source}
/
{incidentId}
/
investigation
Agent tool submit investigation
curl --request POST \
  --url https://api.example.com/api/v2/workspaces/{workspaceId}/agent/tools/incidents/{source}/{incidentId}/investigation \
  --header 'Content-Type: application/json' \
  --data '
{
  "comment": "<string>",
  "classification_reason_comment": "<string>",
  "malicious_score": 123,
  "classification": "BenignPositive",
  "classification_reason": "InaccurateData",
  "classification_sop": {
    "id": "<string>",
    "name": "<string>"
  },
  "response_sops": [
    {
      "id": "<string>",
      "name": "<string>"
    }
  ],
  "gamebook_ids": [
    "<string>"
  ],
  "tool_calls": [
    {
      "name": "<string>",
      "time": "2023-11-07T05:31:56Z",
      "duration_ms": 123,
      "target_entity": "<string>",
      "kql": {
        "query": "<string>",
        "row_count": 123
      }
    }
  ]
}
'
{
  "data": {
    "success": true,
    "summary": "<string>",
    "previous_status": "<string>",
    "new_status": "<string>",
    "applied_classification": "<string>",
    "applied_classification_reason": "<string>",
    "comment_posted": true,
    "status_updated": true
  },
  "meta": {
    "requestId": "<string>",
    "timestamp": "<string>"
  }
}

Documentation Index

Fetch the complete documentation index at: https://docs.contraforce.com/llms.txt

Use this file to discover all available pages before exploring further.

Path Parameters

​
workspaceId
string<uuid>
required
​
source
enum<string>
required
Available options:
Sentinel,
DefenderXDR,
QRadar,
Splunk,
CrowdStrike,
SentinelOne
​
incidentId
string
required

Body

application/json

Request DTO for the agent's submit-investigation tool — the closeout call the agent makes after it has finished investigating an incident.

​
comment
null | string

Final investigation summary. Posted on the incident as the agent's comment as-is — no server-side wrapping or section headers are applied. Write as a detailed security analyst would: cover initial hypothesis, indicators matched, tools called and why, evidence found, classification rationale, response actions, and recommended next steps. This is what a human analyst will read to learn from the agent's analysis.

​
classification_reason_comment
null | string

Short rationale (1–2 sentences) shown on the incident's closure record when the status transition closes the incident. Surfaces in the closure dialog and audit log alongside the classification reason.

​
malicious_score

Agent's maliciousness confidence on a 0–100 scale. 0 = clearly benign, 100 = clearly malicious. Values outside this range cause the call to fail with success:false.

​
classification
null | any

Final incident classification. Allowed values: TruePositive (confirmed malicious), FalsePositive (alert was wrong), BenignPositive (real activity but not malicious), Undetermined (insufficient evidence), Suspicious (SentinelOne incidents only — suspicious but not confirmable). Status transition follows from this via the per-severity agent settings.

Available options:
BenignPositive,
FalsePositive,
TruePositive,
Undetermined,
InformationalExpectedActivity,
Unknown,
NonIssue,
PolicyViolation,
QradarFalsePositive,
Undefined,
Suspicious,
null
​
classification_reason
null | any

Reason corresponding to the classification. TruePositive → Malware | Phishing | Other. FalsePositive → InaccurateData | IncorrectAlertLogic | Other. BenignPositive/Undetermined → Other. Not set for Suspicious. Wrong pairings are normalised server-side and may result in an unexpected applied reason.

Available options:
InaccurateData,
IncorrectAlertLogic,
SuspiciousActivity,
SuspiciousButExpected,
Unknown,
Apt,
Malware,
SecurityPersonnel,
SecurityTesting,
UnwantedSoftware,
Other,
MultistagedAttack,
CompromisedUser,
Phishing,
MaliciousUserActivity,
NotMalicious,
NoEnoughDataToValidate,
ConfirmedUserActivity,
LineOfBusinessApplication,
null
​
classification_sop
object

The single classification SOP whose decision tree drove the classification. Null when no SOP applied to this incident type.

​
response_sops
null | object[]

SOPs whose response steps the agent executed during the investigation. Empty when the agent decided no response action was warranted.

​
gamebook_ids
null | string[]

IDs of gamebooks the agent queued earlier via submit-gamebook during this investigation. Use the gamebook_id returned by each submit-gamebook call. Receive-only here — submit-investigation does NOT queue additional gamebooks.

​
tool_calls
null | object[]

Per-tool-call timeline the agent recorded during the investigation. Used to render the activity header on the comment so an analyst can see exactly which tools the agent invoked, on what target, in what order, and how long each took.

Response

OK

Standard v2 API response envelope for single-item responses.

​
data
object

Result of an agent submit-investigation tool call.

​
meta
object