> ## 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. # Agent tool submit investigation ## OpenAPI ````yaml /api-reference/openapi.json post /api/v2/workspaces/{workspaceId}/agent/tools/incidents/{source}/{incidentId}/investigation openapi: 3.1.1 info: title: ContraForce API description: ContraForce platform API for security operations management. version: '2.0' servers: [] security: [] tags: - name: Incidents - name: Gamebooks - name: Data sources - name: Service tickets - name: Investigation - name: agent-tools - name: Cross-workspace incidents - name: Cross-workspace gamebooks - name: Cross-workspace data sources - name: Webhooks - name: Service accounts - name: Users - name: Azure resources paths: /api/v2/workspaces/{workspaceId}/agent/tools/incidents/{source}/{incidentId}/investigation: post: tags: - agent-tools summary: Agent tool submit investigation operationId: v2-agent-tool-submit-investigation parameters: - name: workspaceId in: path required: true schema: type: string format: uuid - name: source in: path required: true schema: $ref: '#/components/schemas/IncidentSource' - name: incidentId in: path required: true schema: type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/AgentToolInvestigationSubmissionRequest' responses: '200': description: OK content: application/json: schema: $ref: >- #/components/schemas/ApiResponseOfAgentToolInvestigationSubmissionResult '400': description: Bad request — validation or parameter binding failed. content: application/problem+json: schema: $ref: '#/components/schemas/ApiProblemDetails' '401': description: Unauthorized — missing or invalid Bearer token. content: application/problem+json: schema: $ref: '#/components/schemas/ApiProblemDetails' '403': description: Forbidden — insufficient scope or workspace access. content: application/problem+json: schema: $ref: '#/components/schemas/ApiProblemDetails' '404': description: Not found — workspace or resource is missing. content: application/problem+json: schema: $ref: '#/components/schemas/ApiProblemDetails' '500': description: Internal server error. content: application/problem+json: schema: $ref: '#/components/schemas/ApiProblemDetails' components: schemas: IncidentSource: enum: - Sentinel - DefenderXDR - QRadar - Splunk - CrowdStrike - SentinelOne AgentToolInvestigationSubmissionRequest: type: object properties: comment: type: - 'null' - string description: >- 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: type: - 'null' - string description: >- 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: pattern: ^-?(?:0|[1-9]\d*)$ type: - integer - string description: >- 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. format: int32 classification: oneOf: - type: 'null' - $ref: '#/components/schemas/Classification' description: >- 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. classification_reason: oneOf: - type: 'null' - $ref: '#/components/schemas/ClassificationReason' description: >- 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. classification_sop: $ref: '#/components/schemas/AgentToolSopReference' description: >- The single classification SOP whose decision tree drove the classification. Null when no SOP applied to this incident type. response_sops: type: - 'null' - array items: $ref: '#/components/schemas/AgentToolSopReference' description: >- SOPs whose response steps the agent executed during the investigation. Empty when the agent decided no response action was warranted. gamebook_ids: type: - 'null' - array items: type: string description: >- 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: type: - 'null' - array items: $ref: '#/components/schemas/AgentToolCallRecord' description: >- 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. description: >- Request DTO for the agent's submit-investigation tool — the closeout call the agent makes after it has finished investigating an incident. ApiResponseOfAgentToolInvestigationSubmissionResult: type: object properties: data: $ref: '#/components/schemas/AgentToolInvestigationSubmissionResult' meta: $ref: '#/components/schemas/ResponseMeta' description: Standard v2 API response envelope for single-item responses. ApiProblemDetails: type: object properties: type: type: - 'null' - string title: type: - 'null' - string status: pattern: ^-?(?:0|[1-9]\d*)$ type: - 'null' - integer - string format: int32 detail: type: - 'null' - string instance: type: - 'null' - string code: type: - 'null' - string requestId: type: - 'null' - string timestamp: type: - 'null' - string target: type: - 'null' - string errors: type: - 'null' - object additionalProperties: type: array items: type: string description: >- API extension of ProblemDetails that surfaces the stable error code, trace identifier, timestamp, optional target, and optional field-keyed validation error map alongside the RFC 7807 members. Classification: enum: - BenignPositive - FalsePositive - TruePositive - Undetermined - InformationalExpectedActivity - Unknown - NonIssue - PolicyViolation - QradarFalsePositive - Undefined - Suspicious - null ClassificationReason: enum: - InaccurateData - IncorrectAlertLogic - SuspiciousActivity - SuspiciousButExpected - Unknown - Apt - Malware - SecurityPersonnel - SecurityTesting - UnwantedSoftware - Other - MultistagedAttack - CompromisedUser - Phishing - MaliciousUserActivity - NotMalicious - NoEnoughDataToValidate - ConfirmedUserActivity - LineOfBusinessApplication - null AgentToolSopReference: type: object properties: id: type: - 'null' - string description: >- Internal SOP identifier (UUID or slug). Used to link back to the SOP record in the knowledge base. name: type: - 'null' - string description: >- Display name of the SOP. Shown in the comment header so the analyst sees which SOP drove the decision without a follow-up lookup. description: >- A reference to a Standard Operating Procedure used by the agent — both the SOP's internal id and its display name are sent so the metadata is self-describing without a follow-up lookup. AgentToolCallRecord: type: object properties: name: type: - 'null' - string description: >- Tool name as the agent invoked it (e.g. 'execute-kql', 'get-user-details', 'list-signin-logs'). Use the MCP tool name verbatim so the activity header maps to the right icon/label. time: type: string description: UTC instant the tool call started. ISO 8601 / RFC 3339 format. format: date-time duration_ms: pattern: ^-?(?:0|[1-9]\d*)$ type: - integer - string description: >- Wall-clock duration of the call in milliseconds, including network time. Used to surface slow tool calls in the activity header. format: int64 target_entity: type: - 'null' - string description: >- Entity the tool call targeted — UPN for users, device ID for hosts, table name for KQL, etc. Null for tools that do not address a specific entity (e.g. list-kql-tables). kql: $ref: '#/components/schemas/AgentToolCallKql' description: >- KQL-specific detail. Populate ONLY for execute-kql tool calls — the renderer shows the query and row count inline in the activity header. Null for every other tool. description: One entry in the agent's tool-call timeline. AgentToolInvestigationSubmissionResult: type: object properties: success: type: boolean description: >- True when both the comment was posted and the status transition (if any) succeeded. False if either failed — see `comment_posted` and `status_updated` for which leg failed. summary: type: - 'null' - string description: >- Compact human-readable digest of what happened: comment posted? status changed from X to Y? failure reason if any. previous_status: type: - 'null' - string description: Status the incident was in before this call. new_status: type: - 'null' - string description: >- Status the incident is in after this call. Equals previous_status when no transition was applied (either because the status already matched the target or because the update failed). applied_classification: type: - 'null' - string description: >- Classification actually applied after server-side normalisation (e.g. provider-specific value normalisation). May differ from what was sent. applied_classification_reason: type: - 'null' - string description: >- Classification reason actually applied after server-side normalisation. May differ from what was sent. comment_posted: type: boolean description: >- True when the agent's comment was successfully posted on the incident. status_updated: type: boolean description: >- True when the incident's status was successfully transitioned. False when the status was already at the target value (no update needed) or when the update failed. description: Result of an agent submit-investigation tool call. ResponseMeta: type: object properties: requestId: type: - 'null' - string timestamp: type: - 'null' - string AgentToolCallKql: type: object properties: query: type: - 'null' - string description: >- Exact KQL query that was executed. Shown verbatim in the comment activity header so an analyst can replay or audit the query. row_count: pattern: ^-?(?:0|[1-9]\d*)$ type: - integer - string description: >- Number of rows the query returned before any client-side truncation. Use the row_count from the execute-kql tool result. format: int32 description: >- Per-call detail emitted alongside an `execute-kql` tool call so the comment header can render the query and result size without a re-execution. ````