> ## 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 gamebook ## OpenAPI ````yaml /api-reference/openapi.json post /api/v2/workspaces/{workspaceId}/agent/tools/incidents/{source}/{incidentId}/gamebooks 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}/gamebooks: post: tags: - agent-tools summary: Agent tool submit gamebook operationId: v2-agent-tool-submit-gamebook 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/AgentToolGamebookSubmissionRequest' responses: '200': description: OK content: application/json: schema: $ref: >- #/components/schemas/ApiResponseOfAgentToolGamebookSubmissionResult '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 AgentToolGamebookSubmissionRequest: type: object properties: incident_number: pattern: ^-?(?:0|[1-9]\d*)$ type: - integer - string description: >- Sequential incident number from the source platform. Used in human-readable summaries and gamebook tracking. format: int32 incident_title: type: - 'null' - string description: >- Human-readable incident title from the source platform. Used in summaries and audit logs. trigger_type: $ref: '#/components/schemas/AgentTriggerType' description: >- How the agent run was triggered. OnQueue (background): subject to per-severity Gamebooks capability gating — submissions are rejected for severities where Gamebooks is not enabled. ManualInvestigateAndRespond (operator-requested): always allowed to submit gamebooks regardless of capability settings. playbooks: type: - 'null' - array items: $ref: '#/components/schemas/AgentToolPlaybook' description: >- Ordered playbook actions to run as part of this gamebook. Each entry binds a playbook from the registered catalog to its target entity. Must contain at least one entry — empty arrays are rejected. description: >- Request DTO for the agent's submit-gamebook tool. Allows the agent to queue one or more remediation gamebooks against an incident as it investigates. ApiResponseOfAgentToolGamebookSubmissionResult: type: object properties: data: $ref: '#/components/schemas/AgentToolGamebookSubmissionResult' 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. AgentTriggerType: enum: - OnQueue - ManualInvestigateOnly - ManualInvestigateAndRespond description: >- Define the type of the agent trigger that identifies the behaviour of the agent AgentToolPlaybook: type: object properties: playbook_id: type: - 'null' - string description: >- ID of a playbook from the registered playbook catalog. Unknown IDs cause the entire submission to fail — there is no partial-success mode. entity_id: type: - 'null' - string description: >- Stable identifier of the target entity. MUST be the entity object's `id` property — NEVER `aadUserId`, `DeviceId`, `FileHash`, or any other entity-specific property. Using the wrong identifier here will cause the playbook to act on the wrong target or fail. affected_entity: type: - 'null' - string description: >- Display name of the target entity (e.g. UPN for a user, hostname for a device). Shown in human-readable summaries and audit logs. sequence: pattern: ^-?(?:0|[1-9]\d*)$ type: - integer - string description: >- Run order within the gamebook, starting at 1. Lower numbers execute first. Use this to express dependencies — e.g., scan endpoint (sequence 1) before isolate endpoint (sequence 2) on the same device. Sequence is independent per entity: playbooks targeting different entities run in parallel groups. format: int32 AgentToolGamebookSubmissionResult: type: object properties: success: type: boolean description: >- True when the gamebook was queued. False for application-level failures (severity gating, unknown playbook, missing entity properties, upstream errors) — the failure reason is in `summary`. summary: type: - 'null' - string description: >- Compact human-readable digest the agent can quote directly. On success: 'Gamebook GB-XXXXXX queued for {severity} severity incident. N playbook(s) scheduled: …'. On failure: a one-line failure reason. gamebook_id: type: - 'null' - string description: >- ID of the queued gamebook. Pass this back in `submit-investigation`'s gamebook_ids so the investigation record references the gamebooks the agent triggered. status: type: - 'null' - string description: >- Gamebook lifecycle status at the moment of queueing (e.g. 'Queued', 'Running'). Not authoritative for completion — gamebooks run asynchronously after this call returns. is_queued_for_approval: type: boolean description: >- True when the gamebook was recorded but not started — it is sitting in the analyst's queue waiting for approval. Happens when the trigger type or severity capability doesn't give the agent run-authority (OnQueue without the Gamebooks capability for the incident's severity, or ManualInvestigateOnly). False when the gamebook was run directly. description: >- Result of an agent submit-gamebook tool call. Designed for LLM consumption — the string AgentToolGamebookSubmissionResult.Summary field is a compact human-readable digest the agent can emit directly into chat or chain into follow-up reasoning. ResponseMeta: type: object properties: requestId: type: - 'null' - string timestamp: type: - 'null' - string ````