> ## 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. # Run a gamebook > Requires gamebooks:execute and access to the route workspace. Service accounts may submit new gamebooks only: only documented inputs are accepted; portal approval, retry, and internal state fields are rejected. Playbook sequence values must contain exactly 1..N without duplicates or gaps. Workspace policies and partner approval settings apply. A 200 response with isQueued=true and status=Pending means the plan awaits portal approval; it has not executed. Use gamebooks:read to poll history. Service accounts cannot approve, retry, deny, or cancel gamebooks. ## OpenAPI ````yaml /api-reference/openapi.json post /api/v2/workspaces/{workspaceId}/gamebooks/run 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}/gamebooks/run: post: tags: - Gamebooks summary: Run a gamebook description: >- Requires gamebooks:execute and access to the route workspace. Service accounts may submit new gamebooks only: only documented inputs are accepted; portal approval, retry, and internal state fields are rejected. Playbook sequence values must contain exactly 1..N without duplicates or gaps. Workspace policies and partner approval settings apply. A 200 response with isQueued=true and status=Pending means the plan awaits portal approval; it has not executed. Use gamebooks:read to poll history. Service accounts cannot approve, retry, deny, or cancel gamebooks. operationId: v2-run-gamebook parameters: - name: workspaceId in: path required: true schema: type: string format: uuid requestBody: content: application/json: schema: $ref: '#/components/schemas/RunGamebookRequest' required: true responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/ApiResponseOfRunGamebookResponse' '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' '415': description: Unsupported Media Type 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: RunGamebookRequest: required: - incidentId - incidentTitle - source - playbooks type: object properties: incidentId: type: string description: Incident identifier in the authorized route workspace. incidentTitle: type: string description: Required non-empty incident display title. incidentNumber: pattern: ^-?(?:0|[1-9]\d*)$ type: - integer - string description: Optional incident display number. format: int32 source: $ref: '#/components/schemas/IncidentSource' description: Detection source of the incident. isQueued: type: boolean description: >- Requests human approval. False never overrides server-side approval requirements. playbooks: type: array items: $ref: '#/components/schemas/RunGamebookPlaybookRequest' description: Public v2 inputs for one catalog action and its incident target. description: >- Actions with unique, contiguous sequence values from 1 through the number of actions. additionalProperties: false description: >- Public v2 inputs for a new gamebook submission, without portal approval or executor state. ApiResponseOfRunGamebookResponse: type: object properties: data: $ref: '#/components/schemas/RunGamebookResponse' description: >- Public result of submitting a gamebook, without workspace or incident target details. 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. IncidentSource: enum: - Sentinel - DefenderXDR - QRadar - Splunk - CrowdStrike - SentinelOne - SumoLogic RunGamebookPlaybookRequest: required: - id - entityType - sequence type: object properties: id: type: string description: Playbook identifier from the catalog. entityId: type: - 'null' - string description: >- Exact incident entity identifier. General actions do not require a target. entityType: $ref: '#/components/schemas/RunGamebookEntityType' description: >- Action category matching the playbook catalog, not the incident entity kind. sequence: pattern: ^-?(?:0|[1-9]\d*)$ type: - integer - string description: >- One-based execution position; the complete plan must contain exactly 1..N. format: int32 parameters: type: - 'null' - object description: >- Optional action configuration, such as the network resource settings for Block IP. additionalProperties: false description: Public v2 inputs for one catalog action and its incident target. RunGamebookResponse: required: - id - status - isQueued type: object properties: id: type: string description: >- Identifier of the submitted gamebook, for subsequent history lookups. status: $ref: '#/components/schemas/RunGamebookStatus' description: Current execution status of the submitted gamebook. isQueued: type: boolean description: >- Whether the gamebook is waiting for portal approval rather than executing. description: >- Public result of submitting a gamebook, without workspace or incident target details. ResponseMeta: type: object properties: requestId: type: - 'null' - string timestamp: type: - 'null' - string RunGamebookEntityType: enum: - User - Endpoint - General - Network - Email description: Action categories supported by the v2 gamebook submission contract. RunGamebookStatus: enum: - Pending - Running - Finished - Failed - Queued - Denied - Cancelled description: Execution states exposed by the public v2 gamebook submission result. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.