Contraforce Gamebooks API

openapi: 3.2.0
info:
  title: ContraForce Gamebooks API
  description: ContraForce platform API for security operations management.
  version: '2.0'
tags:
- name: Gamebooks
paths:
  /api/v2/workspaces/{workspaceId}/gamebooks/rules/{incidentTitle}:
    get:
      tags:
      - Gamebooks
      summary: Get playbooks by incident title
      operationId: v2-get-playbooks-by-incident-title
      parameters:
      - name: workspaceId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      - name: incidentTitle
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponseOfIEnumerableOfPlaybookMetadataDto'
        '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'
  /api/v2/workspaces/{workspaceId}/gamebooks/history:
    get:
      tags:
      - Gamebooks
      summary: List gamebooks history
      operationId: v2-list-gamebooks-history
      parameters:
      - name: workspaceId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      - name: query
        in: query
        schema:
          type: string
      - name: pageToken
        in: query
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponseOfListGamebooksResultDto'
        '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'
  /api/v2/workspaces/{workspaceId}/gamebooks/history/{gamebookId}/playbooks:
    get:
      tags:
      - Gamebooks
      summary: Get playbooks by gamebook id
      operationId: v2-get-playbooks-by-gamebook-id
      parameters:
      - name: workspaceId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      - name: gamebookId
        in: path
        required: true
        schema:
          type: string
      - name: year
        in: query
        required: true
        schema:
          pattern: ^-?(?:0|[1-9]\d*)$
          type:
          - integer
          - string
          format: int32
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponseOfIEnumerableOfPlaybookGameplanDto'
        '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'
  /api/v2/workspaces/{workspaceId}/gamebooks/by-incident/{incidentId}:
    get:
      tags:
      - Gamebooks
      summary: List incident gamebooks
      operationId: v2-list-incident-gamebooks
      parameters:
      - name: workspaceId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      - name: incidentId
        in: path
        required: true
        schema:
          type: string
      - name: withUserDetails
        in: query
        required: true
        schema:
          type: boolean
      - name: source
        in: query
        schema:
          $ref: '#/components/schemas/IncidentSource'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponseOfIEnumerableOfGamebookDto'
        '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'
  /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:
        '415':
          description: Unsupported Media Type
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ApiProblemDetails'
        '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'
        '500':
          description: Internal server error.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ApiProblemDetails'
components:
  schemas:
    PlaybookMetadataDto:
      type: object
      properties:
        playbookId:
          type:
          - 'null'
          - string
        playbookName:
          type:
          - 'null'
          - string
        playbookDescription:
          type:
          - 'null'
          - string
        incidentTitle:
          type:
          - 'null'
          - string
        entity:
          type:
          - 'null'
          - string
        sentinelEntities:
          type:
          - 'null'
          - array
          items:
            type: string
        recoverPlaybookId:
          type:
          - 'null'
          - string
        isAdminRequired:
          type: boolean
    ResponseMeta:
      type: object
      properties:
        requestId:
          type:
          - 'null'
          - string
        timestamp:
          type:
          - 'null'
          - string
    ApiResponseOfIEnumerableOfPlaybookMetadataDto:
      type: object
      properties:
        data:
          type:
          - 'null'
          - array
          items:
            $ref: '#/components/schemas/PlaybookMetadataDto'
        meta:
          $ref: '#/components/schemas/ResponseMeta'
      description: Standard v2 API response envelope for single-item responses.
    RunGamebookResponse:
      required:
      - id
      - status
      - isQueued
      type: object
      properties:
        id:
          type: string
          description: Identifier of the submitted gamebook, for subsequent history lookups.
        status:
          description: Current execution status of the submitted gamebook.
          $ref: '#/components/schemas/RunGamebookStatus'
        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.
    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.'
    ApiResponseOfIEnumerableOfPlaybookGameplanDto:
      type: object
      properties:
        data:
          type:
          - 'null'
          - array
          items:
            $ref: '#/components/schemas/PlaybookGameplanDto'
        meta:
          $ref: '#/components/schemas/ResponseMeta'
      description: Standard v2 API response envelope for single-item responses.
    RunGamebookStatus:
      enum:
      - Pending
      - Running
      - Finished
      - Failed
      - Queued
      - Denied
      - Cancelled
      description: Execution states exposed by the public v2 gamebook submission result.
    GamebookDto:
      type: object
      properties:
        id:
          type:
          - 'null'
          - string
        tracingId:
          type:
          - 'null'
          - string
        incidentId:
          type:
          - 'null'
          - string
        source:
          description: Source of the system that owns the incident Sentinel, Defender ATP, etc.
          $ref: '#/components/schemas/IncidentSource'
        incidentTitle:
          type:
          - 'null'
          - string
        incidentNumber:
          pattern: ^-?(?:0|[1-9]\d*)$
          type:
          - integer
          - string
          format: int32
        isOcr:
          type: boolean
        isRecover:
          type: boolean
        triggedByUserId:
          type:
          - 'null'
          - string
        displayName:
          type:
          - 'null'
          - string
        modificationDate:
          type: string
          format: date-time
        creationDate:
          type: string
          format: date-time
        status:
          $ref: '#/components/schemas/GamebookRunningStatus'
        title:
          type:
          - 'null'
          - string
        isAdminRequired:
          type: boolean
        workspaceId:
          type:
          - 'null'
          - string
        workspaceName:
          type:
          - 'null'
          - string
        tenantId:
          type:
          - 'null'
          - string
        isAutoRun:
          type: boolean
        originalGamebookId:
          type:
          - 'null'
          - string
          description: Used if the gamebook is retry gamebook and refers to the id of the gamebook id that has been retried
        originalGamebookTitle:
          type:
          - 'null'
          - string
          description: Used if the gamebook is retry gamebook and refers to the id of the gamebook title that has been retried
        isRetryGamebook:
          type: boolean
          description: Indicator if the gamebook is a retry to failed gamebook
        isQueued:
          type: boolean
          description: Indicator if the gamebook is queued by a service provider and it is not started yet
        playbooks:
          type:
          - 'null'
          - array
          items:
            $ref: '#/components/schemas/PlaybookGameplanDto'
        summary:
          type:
          - 'null'
          - string
    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:
          description: Detection source of the incident.
          $ref: '#/components/schemas/IncidentSource'
        isQueued:
          type: boolean
          description: Requests human approval. False never overrides server-side approval requirements.
        playbooks:
          type: array
          items:
            description: Public v2 inputs for one catalog action and its incident target.
            $ref: '#/components/schemas/RunGamebookPlaybookRequest'
          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.
    ApiResponseOfIEnumerableOfGamebookDto:
      type: object
      properties:
        data:
          type:
          - 'null'
          - array
          items:
            $ref: '#/components/schemas/GamebookDto'
        meta:
          $ref: '#/components/schemas/ResponseMeta'
      description: Standard v2 API response envelope for single-item responses.
    ApiResponseOfListGamebooksResultDto:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/ListGamebooksResultDto'
        meta:
          $ref: '#/components/schemas/ResponseMeta'
      description: Standard v2 API response envelope for single-item responses.
    ListGamebooksResultDto:
      type: object
      properties:
        gamebooks:
          type:
          - 'null'
          - array
          items:
            $ref: '#/components/schemas/GamebookDto'
        pageToken:
          type:
          - 'null'
          - string
        totalCount:
          pattern: ^-?(?:0|[1-9]\d*)$
          type:
          - integer
          - string
          format: int32
    IncidentSource:
      enum:
      - Sentinel
      - DefenderXDR
      - QRadar
      - Splunk
      - CrowdStrike
      - SentinelOne
      - SumoLogic
    PlaybookRunningStatus:
      enum:
      - Pending
      - Running
      - Finished
      - Failed
      - Terminated
    ApiResponseOfRunGamebookResponse:
      type: object
      properties:
        data:
          description: Public result of submitting a gamebook, without workspace or incident target details.
          $ref: '#/components/schemas/RunGamebookResponse'
        meta:
          $ref: '#/components/schemas/ResponseMeta'
      description: Standard v2 API response envelope for single-item responses.
    PlaybookEntityType:
      enum:
      - User
      - Endpoint
      - General
      - Network
      - Email
    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:
          description: Action category matching the playbook catalog, not the incident entity kind.
          $ref: '#/components/schemas/RunGamebookEntityType'
        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.
    GamebookRunningStatus:
      enum:
      - Pending
      - Running
      - Finished
      - Failed
      - Queued
      - Denied
      - Cancelled
    RunGamebookEntityType:
      enum:
      - User
      - Endpoint
      - General
      - Network
      - Email
      description: Action categories supported by the v2 gamebook submission contract.
    PlaybookGameplanDto:
      type: object
      properties:
        id:
          type:
          - 'null'
          - string
        referenceId:
          type:
          - 'null'
          - string
          description: 'Stable identity of a plan item — the playbook id combined with the target it acts on.

            Used for the gamebook plan''s de-duplication, equality, and the V2 list `@key`.'
        entityId:
          type:
          - 'null'
          - string
        name:
          type:
          - 'null'
          - string
        userObjectId:
          type:
          - 'null'
          - string
          description: 'Azure AD object id (GUID) of the user/mailbox a playbook should act on, supplied

            directly by the caller instead of being resolved from the incident''s entities.'
        userPrincipalName:
          type:
          - 'null'
          - string
          description: 'User principal name (UPN) of the user/mailbox a playbook should act on, supplied

            directly by the caller instead of being resolved from the incident''s entities.'
        internetMessageId:
          type:
          - 'null'
          - string
          description: 'RFC 2822 internet message id of the email an email playbook should act on, supplied

            directly by the caller instead of being read from the incident''s email entity.'
        description:
          type:
          - 'null'
          - string
        entityType:
          $ref: '#/components/schemas/PlaybookEntityType'
        affectedEntity:
          type:
          - 'null'
          - string
        isRecommended:
          type: boolean
        status:
          $ref: '#/components/schemas/PlaybookRunningStatus'
        errorMessage:
          type:
          - 'null'
          - string
        sequence:
          pattern: ^-?(?:0|[1-9]\d*)$
          type:
          - integer
          - string
          format: int32
        modificationDate:
          type: string
          format: date-time
        startingDate:
          type:
          - 'null'
          - string
          format: date-time
        finishingDate:
          type:
          - 'null'
          - string
          format: date-time
        executionTime:
          type:
          - 'null'
          - string
          description: Total execution time taken to execute the playbook, the value is null until the DateTime? PlaybookGameplanDto.FinishingDate property is populated
        tracingId:
          type:
          - 'null'
          - string
        parameters:
          type:
          - 'null'
          - object
          description: 'Represents the parameters of the playbooks to be sent in the message

            The value will be populated only if the playbook is configurable (Block IP)'
        isAdminRequired:
          type: boolean