> ## 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: Export - 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 - SumoLogic 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: >- How malicious the agent judged the activity, 0 to 100, where 0 is clearly benign and 100 is clearly malicious. This is not confidence in the verdict: a False Positive the agent is certain about scores near zero, not near a hundred. format: int32 classification: oneOf: - type: 'null' - $ref: '#/components/schemas/Classification' description: >- Final incident classification, identical for every security platform. Allowed values: TruePositive (confirmed malicious), FalsePositive (the detection was wrong; no suspicious activity occurred), BenignPositive (real activity confirmed benign, expected, or authorized), Undetermined (no firm verdict reached). 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; required on every classified closeout and identical for every security platform. TruePositive → MultistagedAttack | Malware | MaliciousUserActivity | UnwantedSoftware | Phishing | CompromisedUser | Apt | SuspiciousActivity | Other. FalsePositive → NotMalicious | NoEnoughDataToValidate | InaccurateData | IncorrectAlertLogic | Other. BenignPositive → SecurityTesting | ConfirmedUserActivity | LineOfBusinessApplication | SecurityPersonnel | SuspiciousButExpected | Other. Undetermined → Unknown | Other. Pick the most specific reason the evidence supports; a pairing outside this list is normalized server-side to Other. 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: >- 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. 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: One entry in the agent's tool-call timeline. 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' description: Result of an agent submit-investigation tool call. 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 - 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. REQUIRED on every execute-kql tool call and null for every other tool. Carry the exact query text you passed to execute-kql in `query` and the tool result's row_count in `row_count`: the portal shows the query to the analyst on the comment, lets them re-run it in log search, and audits it. An execute-kql entry without `query` cannot be reviewed or replayed. 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. Null when no status transition was applied. applied_classification_reason: type: - 'null' - string description: >- Classification reason actually applied after server-side normalisation. Null when no status transition was applied. 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. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.