openapi: 3.2.0
info:
  title: Case Manager API
  version: 1.0.0
servers:
- url: /airmdrapi
tags:
- name: Case Manager
paths:
  /case:
    post:
      tags:
      - Case Manager
      operationId: createCaseAPI
      summary: create a new case
      parameters:
      - name: User-ID
        in: header
        description: The User ID of the requestor.
        required: true
        schema:
          type: string
      - name: Organization-ID
        in: header
        description: The Organization ID associated with the requestor.
        required: true
        schema:
          type: string
      - name: X-Request-ID
        in: header
        description: The ID associated with the request
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateCaseRequest'
      security:
      - SessionCookie: []
      responses:
        '200':
          description: case created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateCaseResponse'
        default:
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /case/{case_uuid}:
    get:
      tags:
      - Case Manager
      operationId: getCaseAPI
      summary: get details of a case
      parameters:
      - name: User-ID
        in: header
        description: The User ID of the requestor.
        required: true
        schema:
          type: string
      - name: Organization-ID
        in: header
        description: The Organization ID associated with the requestor.
        schema:
          type: string
      - name: X-Request-ID
        in: header
        description: The ID associated with the request
        schema:
          type: string
      - name: case_uuid
        in: path
        description: The id of the case to be fetched
        required: true
        schema:
          type: string
      - name: requested_view
        in: query
        description: Requested view of the case
        required: true
        schema:
          $ref: '#/components/schemas/CaseView'
      security:
      - SessionCookie: []
      responses:
        '200':
          description: case fetched successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetCaseResponse'
        default:
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    patch:
      tags:
      - Case Manager
      operationId: updateCaseAPI
      summary: update details of a case
      parameters:
      - name: User-ID
        in: header
        description: The User ID of the requestor.
        schema:
          type: string
      - name: Organization-ID
        in: header
        description: The Organization ID associated with the requestor.
        schema:
          type: string
      - name: X-Request-ID
        in: header
        description: The ID associated with the request
        schema:
          type: string
      - name: case_uuid
        in: path
        description: The uuid of the case to be updated
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateCaseRequest'
      security:
      - SessionCookie: []
      responses:
        '200':
          description: case updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpdateCaseResponse'
        default:
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /case/{case_uuid}/email:
    post:
      tags:
      - Case Manager
      operationId: emailCaseDetailsAPI
      summary: email details of a case
      parameters:
      - name: User-ID
        in: header
        description: The User ID of the requestor.
        schema:
          type: string
      - name: Organization-ID
        in: header
        description: The Organization ID associated with the requestor.
        schema:
          type: string
      - name: X-Request-ID
        in: header
        description: The ID associated with the request
        schema:
          type: string
      - name: case_uuid
        in: path
        description: The uuid of the case
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EmailCaseDetailsRequest'
      security:
      - SessionCookie: []
      responses:
        '200':
          description: email sent successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmailCaseDetailsResponse'
        default:
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /case/id/{case_id}:
    get:
      tags:
      - Case Manager
      operationId: getCaseFromIdAPI
      summary: get details of a case from case id
      parameters:
      - name: User-ID
        in: header
        description: The User ID of the requestor.
        required: true
        schema:
          type: string
      - name: Organization-ID
        in: header
        description: The Organization ID associated with the requestor.
        schema:
          type: string
      - name: X-Request-ID
        in: header
        description: The ID associated with the request
        schema:
          type: string
      - name: case_id
        in: path
        description: The unique case id of the case to be fetched
        required: true
        schema:
          type: string
      - name: requested_view
        in: query
        description: Requested view of the case
        required: true
        schema:
          $ref: '#/components/schemas/CaseView'
      security:
      - SessionCookie: []
      responses:
        '200':
          description: case fetched successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetCaseResponse'
        default:
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /case/list:
    post:
      tags:
      - Case Manager
      operationId: getCasesForOrgAPI
      summary: get case list for an organization based on filter and sort
      parameters:
      - name: User-ID
        in: header
        description: The User ID of the requestor.
        required: true
        schema:
          type: string
      - name: Organization-ID
        in: header
        description: The Organization ID associated with the requestor.
        schema:
          type: string
      - name: X-Request-ID
        in: header
        description: The ID associated with the request
        schema:
          type: string
      - name: page
        in: query
        description: Page number for paginated results.
        required: true
        schema:
          type: integer
      - name: size
        in: query
        description: Number of results per page.
        required: true
        schema:
          type: integer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CaseListRequest'
      security:
      - SessionCookie: []
      responses:
        '200':
          description: List of cases retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CaseListResponse'
        default:
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /case/bulk:
    delete:
      tags:
      - Case Manager
      operationId: archiveCasesAPI
      summary: archive cases for given uuids
      parameters:
      - name: User-ID
        in: header
        description: The User ID of the requestor.
        required: true
        schema:
          type: string
      - name: Organization-ID
        in: header
        description: The Organization ID associated with the requestor.
        schema:
          type: string
      - name: X-Request-ID
        in: header
        description: The ID associated with the request
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ArchiveCasesRequest'
      security:
      - SessionCookie: []
      responses:
        '200':
          description: case archived successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ArchiveCasesResponse'
        default:
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /v2/case/bulk:
    delete:
      tags:
      - Case Manager
      operationId: archiveCasesAPIV2
      summary: archive cases for given uuids
      parameters:
      - name: User-ID
        in: header
        description: The User ID of the requestor.
        required: true
        schema:
          type: string
      - name: Organization-ID
        in: header
        description: The Organization ID associated with the requestor.
        schema:
          type: string
      - name: X-Request-ID
        in: header
        description: The ID associated with the request
        schema:
          type: string
      - name: Execution-ID
        in: header
        description: ID of the execution if action is perfomed through a darryl action
        schema:
          type: string
      - name: Organization-Hosturl
        in: header
        description: The host url of the organization
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ArchiveCasesRequest'
      security:
      - SessionCookie: []
      responses:
        '200':
          description: case archived successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ArchiveCasesResponse'
        default:
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /v2/case/bulk/hard_delete:
    delete:
      tags:
      - Case Manager
      operationId: bulkDeleteCasesAPIV2
      summary: hard delete cases for given uuids
      parameters:
      - name: User-ID
        in: header
        description: The User ID of the requestor.
        required: true
        schema:
          type: string
      - name: Organization-ID
        in: header
        description: The Organization ID associated with the requestor.
        schema:
          type: string
      - name: X-Request-ID
        in: header
        description: The ID associated with the request
        schema:
          type: string
      - name: Organization-Hosturl
        in: header
        description: The host url of the organization
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BulkDeleteCasesRequest'
      security:
      - SessionCookie: []
      responses:
        '200':
          description: cases deleted successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BulkDeleteCasesResponse'
        default:
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /case/{case_identifier}/chat_session/{chat_session_id}/link:
    post:
      tags:
      - Case Manager
      operationId: linkChatSessionToCaseAPI
      summary: Link given chat session to case
      parameters:
      - name: User-ID
        in: header
        description: The User ID of the requestor.
        required: true
        schema:
          type: string
      - name: Organization-ID
        in: header
        description: The Organization ID associated with the requestor.
        required: true
        schema:
          type: string
      - name: X-Request-ID
        in: header
        description: The ID associated with the request
        schema:
          type: string
      - name: case_identifier
        in: path
        description: Unique identifier (id or uuid) of the case to which chat session will be linked
        schema:
          type: string
      - name: chat_session_id
        in: path
        description: Unique identifier uuid of the chat session to link to the case
        schema:
          type: string
      security:
      - SessionCookie: []
      responses:
        '200':
          description: chat session linked successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Success'
        default:
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /case/{case_identifier}/chat_session/{chat_session_id}/unlink:
    post:
      tags:
      - Case Manager
      operationId: unlinkChatSessionToCaseAPI
      summary: Unlink given session from case
      parameters:
      - name: User-ID
        in: header
        description: The User ID of the requestor.
        required: true
        schema:
          type: string
      - name: Organization-ID
        in: header
        description: The Organization ID associated with the requestor.
        required: true
        schema:
          type: string
      - name: X-Request-ID
        in: header
        description: The ID associated with the request
        schema:
          type: string
      - name: case_identifier
        in: path
        description: Unique identifier (id or uuid) of the case from which session will be unlinked
        schema:
          type: string
      - name: chat_session_id
        in: path
        description: Unique identifier uuid of the session to unlink from case
        schema:
          type: string
      security:
      - SessionCookie: []
      responses:
        '200':
          description: session unlinked successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Success'
        default:
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /case/chat_session/{chat_session_id}:
    get:
      tags:
      - Case Manager
      operationId: getLinkedCasesForSessionAPI
      summary: Get linked cases for given session uuid
      parameters:
      - name: User-ID
        in: header
        description: The User ID of the requestor.
        required: true
        schema:
          type: string
      - name: Organization-ID
        in: header
        description: The Organization ID associated with the requestor.
        required: true
        schema:
          type: string
      - name: X-Request-ID
        in: header
        description: The ID associated with the request
        schema:
          type: string
      - name: chat_session_id
        in: path
        description: Unique identifier uuid of the session to unlink from case
        schema:
          type: string
        required: true
      security:
      - SessionCookie: []
      responses:
        '200':
          description: case list fetched successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CaseListResponse'
        default:
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /case/{case_identifier}/cases/link:
    post:
      tags:
      - Case Manager
      operationId: linkCasesAPI
      summary: Link given cases in request to case
      parameters:
      - name: User-ID
        in: header
        description: The User ID of the requestor.
        required: true
        schema:
          type: string
      - name: Organization-ID
        in: header
        description: The Organization ID associated with the requestor.
        required: true
        schema:
          type: string
      - name: X-Request-ID
        in: header
        description: The ID associated with the request
        schema:
          type: string
      - name: case_identifier
        in: path
        description: Unique identifier (id or uuid) of the case to others cases will be linked
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CaseLinkRequest'
      security:
      - SessionCookie: []
      responses:
        '200':
          description: case linked successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Success'
        default:
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /case/{primary_case_identifier}/secondary/case/{secondary_case_identifier}/unlink:
    post:
      tags:
      - Case Manager
      operationId: unlinkCaseAPI
      summary: Unlink given secondary case from primary case
      parameters:
      - name: User-ID
        in: header
        description: The User ID of the requestor.
        required: true
        schema:
          type: string
      - name: Organization-ID
        in: header
        description: The Organization ID associated with the requestor.
        required: true
        schema:
          type: string
      - name: X-Request-ID
        in: header
        description: The ID associated with the request
        schema:
          type: string
      - name: primary_case_identifier
        in: path
        description: Unique identifier (id or uuid) of the case from which secondary case will be unlinked
        schema:
          type: string
      - name: secondary_case_identifier
        in: path
        description: Unique identifier uuid of the secondary case to unlink from primary case
        schema:
          type: string
      security:
      - SessionCookie: []
      responses:
        '200':
          description: case unlinked successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Success'
        default:
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /case/metrics:
    get:
      tags:
      - Case Manager
      operationId: getCaseMetrics
      summary: Retrieve metrics data
      parameters:
      - name: User-ID
        in: header
        description: The User ID of the requestor.
        required: true
        schema:
          type: string
      - name: Organization-ID
        in: header
        description: The Organization ID associated with the requestor.
        schema:
          type: string
      - name: X-Request-ID
        in: header
        description: The ID associated with the request
        schema:
          type: string
      - name: days
        in: query
        description: Number of days to include in the metrics calculation (optional)
        schema:
          type: integer
          minimum: 1
          default: 7
        required: false
      - name: organization_id
        in: query
        description: Additional org id filter. Only applicable for Airmdr employees. If empty, metrics for all organizations are shown.
        schema:
          type: string
      security:
      - SessionCookie: []
      responses:
        '200':
          description: case metrics fetched successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CaseMetricsResponse'
        default:
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /case/analytics/metrics:
    get:
      tags:
      - Case Manager
      operationId: getCaseAnalyticsMetrics
      summary: Retrieve case analytics dashboard metrics
      parameters:
      - name: User-ID
        in: header
        description: The User ID of the requestor.
        required: true
        schema:
          type: string
      - name: Organization-ID
        in: header
        description: The Organization ID associated with the requestor.
        schema:
          type: string
      - name: X-Request-ID
        in: header
        description: The ID associated with the request
        schema:
          type: string
      - name: days
        in: query
        description: Number of days to include in the metrics calculation.
        required: false
        schema:
          type: integer
          minimum: 1
          default: 7
      - name: organization_id
        in: query
        description: Org ID filter. Only applicable for AirMDR employees. If empty, metrics for all accessible organizations are returned.
        required: false
        schema:
          type: string
      - name: created_at_from
        in: query
        description: Start of case creation time range as Unix timestamp (seconds).
        required: false
        schema:
          type: integer
          format: int64
      - name: created_at_to
        in: query
        description: End of case creation time range as Unix timestamp (seconds).
        required: false
        schema:
          type: integer
          format: int64
      - name: force_refresh
        in: query
        description: When true, bypass any cached result and recompute the metrics.
        required: false
        schema:
          type: boolean
          default: false
      security:
      - SessionCookie: []
      responses:
        '200':
          description: Case analytics metrics fetched successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CaseAnalyticsDashboardResponse'
        default:
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /case/soc/metrics:
    get:
      tags:
      - Case Manager
      operationId: getCaseSocPerformanceMetrics
      summary: Retrieve SOC performance dashboard metrics
      parameters:
      - name: User-ID
        in: header
        description: The User ID of the requestor.
        required: true
        schema:
          type: string
      - name: Organization-ID
        in: header
        description: The Organization ID associated with the requestor.
        schema:
          type: string
      - name: X-Request-ID
        in: header
        description: The ID associated with the request
        schema:
          type: string
      - name: days
        in: query
        description: Number of days to include in the metrics calculation.
        required: false
        schema:
          type: integer
          minimum: 1
          default: 7
      - name: organization_id
        in: query
        description: Org ID filter. Only applicable for AirMDR employees. If empty, metrics for all accessible organizations are returned.
        required: false
        schema:
          type: string
      - name: created_at_from
        in: query
        description: Start of case creation time range as Unix timestamp (seconds).
        required: false
        schema:
          type: integer
          format: int64
      - name: created_at_to
        in: query
        description: End of case creation time range as Unix timestamp (seconds).
        required: false
        schema:
          type: integer
          format: int64
      - name: force_refresh
        in: query
        description: When true, bypass any cached result and recompute the metrics.
        required: false
        schema:
          type: boolean
          default: false
      security:
      - SessionCookie: []
      responses:
        '200':
          description: SOC performance metrics fetched successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SocPerformanceDashboardResponse'
        default:
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /case/executive/metrics:
    get:
      tags:
      - Case Manager
      operationId: getCaseExecutiveMetrics
      summary: Retrieve executive dashboard metrics
      parameters:
      - name: User-ID
        in: header
        description: The User ID of the requestor.
        required: true
        schema:
          type: string
      - name: Organization-ID
        in: header
        description: The Organization ID associated with the requestor.
        schema:
          type: string
      - name: X-Request-ID
        in: header
        description: The ID associated with the request
        schema:
          type: string
      - name: days
        in: query
        description: Number of days to include in the metrics calculation.
        required: false
        schema:
          type: integer
          minimum: 1
          default: 7
      - name: organization_id
        in: query
        description: Org ID filter. Only applicable for AirMDR employees. If empty, metrics for all accessible organizations are returned.
        required: false
        schema:
          type: string
      - name: created_at_from
        in: query
        description: Start of case creation time range as Unix timestamp (seconds).
        required: false
        schema:
          type: integer
          format: int64
      - name: created_at_to
        in: query
        description: End of case creation time range as Unix timestamp (seconds).
        required: false
        schema:
          type: integer
          format: int64
      - name: force_refresh
        in: query
        description: When true, bypass any cached result and recompute the metrics.
        required: false
        schema:
          type: boolean
          default: false
      security:
      - SessionCookie: []
      responses:
        '200':
          description: Executive metrics fetched successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExecutiveDashboardResponse'
        default:
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /case/metrics/llm/summary:
    get:
      tags:
      - Case Manager
      operationId: getCaseMetricsLLMSummaryAPI
      summary: Based on the parameters, retrieve LLM generated summary for the metrics data
      parameters:
      - name: User-ID
        in: header
        description: The User ID of the requestor.
        required: true
        schema:
          type: string
      - name: Organization-ID
        in: header
        description: The Organization ID associated with the requestor.
        schema:
          type: string
      - name: X-Request-ID
        in: header
        description: The ID associated with the request
        schema:
          type: string
      - name: days
        in: query
        description: Number of days to include in the metrics calculation (optional)
        schema:
          type: integer
          minimum: 1
          default: 7
        required: false
      - name: organization_id
        in: query
        description: Additional org id filter. Only applicable for Airmdr employees. If empty, metrics for all organizations are shown.
        schema:
          type: string
      - name: metrics_type
        in: query
        required: true
        description: Type of metrics to generate summary for
        schema:
          type: string
          enum:
          - case_analytics
          - soc_performance
          - system_health
          - security_review
          - case_analytics_v2
          - soc_performance_v2
      - name: created_at_from
        in: query
        description: Start of case creation time range as Unix timestamp (seconds).
        required: false
        schema:
          type: integer
          format: int64
      - name: created_at_to
        in: query
        description: End of case creation time range as Unix timestamp (seconds).
        required: false
        schema:
          type: integer
          format: int64
      - name: force_refresh
        in: query
        description: When true, bypass any cached result and recompute the metrics.
        required: false
        schema:
          type: boolean
          default: false
      security:
      - SessionCookie: []
      responses:
        '200':
          description: case metrics summary generated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CaseMetricsSummaryResponse'
        default:
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /case/metrics/detailed:
    post:
      tags:
      - Case Manager
      operationId: getDetailedCaseMetricsAPI
      summary: Retrieve detailed metrics data
      parameters:
      - name: User-ID
        in: header
        description: The User ID of the requestor.
        required: true
        schema:
          type: string
      - name: Organization-ID
        in: header
        description: The Organization ID associated with the requestor.
        schema:
          type: string
      - name: X-Request-ID
        in: header
        description: The ID associated with the request
        schema:
          type: string
      - name: start_time
        in: query
        description: Start time for the metrics calculation
        schema:
          type: integer
          format: int64
          description: Start time for the metrics calculation
        required: true
      - name: end_time
        in: query
        description: End time for the metrics calculation
        schema:
          type: integer
          format: int64
          description: End time for the metrics calculation
        required: true
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GetDetailedMetricsRequest'
      security:
      - SessionCookie: []
      responses:
        '200':
          description: case metrics fetched successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetDetailedMetricsResponse'
        default:
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /case/{case_identifier}/score:
    get:
      tags:
      - Case Manager
      operationId: getCaseScoreAPI
      summary: Get score of a case
      parameters:
      - $ref: '#/components/parameters/user-id'
      - $ref: '#/components/parameters/organization-id'
      - $ref: '#/components/parameters/x-request-id'
      - name: case_identifier
        in: path
        description: case identifier used to identify case
        schema:
          type: string
      security:
      - SessionCookie: []
      responses:
        '200':
          description: case score fetched successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetCaseScoreResponse'
        default:
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    post:
      tags:
      - Case Manager
      operationId: generateCaseScoreAPI
      summary: Generate score for a given case
      parameters:
      - $ref: '#/components/parameters/user-id'
      - $ref: '#/components/parameters/organization-id'
      - $ref: '#/components/parameters/x-request-id'
      - name: case_identifier
        in: path
        description: case identifier used to identify case
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenerateCaseScoreRequest'
      security:
      - SessionCookie: []
      responses:
        '200':
          description: case score generated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenerateCaseScoreResponse'
        default:
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /scoring-guidelines:
    post:
      tags:
      - Case Manager
      operationId: createScoringGuidelinesAPI
      summary: Create a new scoring guidelines
      parameters:
      - $ref: '#/components/parameters/user-id'
      - $ref: '#/components/parameters/organization-id'
      - $ref: '#/components/parameters/x-request-id'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateScoringGuidelinesRequest'
      security:
      - SessionCookie: []
      responses:
        '200':
          description: scoring guidelines created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateScoringGuidelinesResponse'
        default:
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /scoring-guidelines/{guideline_id}:
    get:
      tags:
      - Case Manager
      operationId: getScoringGuidelinesAPI
      summary: Get scoring guidelines
      parameters:
      - $ref: '#/components/parameters/user-id'
      - $ref: '#/components/parameters/organization-id'
      - $ref: '#/components/parameters/x-request-id'
      - name: guideline_id
        in: path
        description: guideline id used to identify guideline
        schema:
          type: string
      security:
      - SessionCookie: []
      responses:
        '200':
          description: scoring guidelines fetched successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetScoringGuidelinesResponse'
        default:
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    put:
      tags:
      - Case Manager
      operationId: updateScoringGuidelinesAPI
      summary: Update a scoring guidelines
      parameters:
      - $ref: '#/components/parameters/user-id'
      - $ref: '#/components/parameters/organization-id'
      - $ref: '#/components/parameters/x-request-id'
      - name: guideline_id
        in: path
        description: guideline id used to identify guideline
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateScoringGuidelinesRequest'
      security:
      - SessionCookie: []
      responses:
        '200':
          description: scoring guidelines updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetScoringGuidelinesResponse'
        default:
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /case/score/list:
    post:
      tags:
      - Case Manager
      operationId: listCaseScoresAPI
      summary: List case scores
      parameters:
      - $ref: '#/components/parameters/user-id'
      - $ref: '#/components/parameters/organization-id'
      - $ref: '#/components/parameters/x-request-id'
      - name: page
        in: query
        required: false
        schema:
          type: integer
      - name: size
        in: query
        required: false
        schema:
          type: integer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ListCaseScoresRequest'
      security:
      - SessionCookie: []
      responses:
        '200':
          description: case scores listed successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListCaseScoresResponse'
        default:
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /case/score/bulk:
    post:
      tags:
      - Case Manager
      operationId: generateBulkCaseScoresAPI
      summary: Generate score for a given cases
      parameters:
      - $ref: '#/components/parameters/user-id'
      - $ref: '#/components/parameters/organization-id'
      - $ref: '#/components/parameters/x-request-id'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenerateBulkCaseScoresRequest'
      security:
      - SessionCookie: []
      responses:
        '200':
          description: case scores generated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenerateBulkCaseScoresResponse'
        default:
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /cost_trim_analysis:
    get:
      tags:
      - Case Manager
      operationId: getCostTrimAnalysis
      summary: Retrieve the cost-trim analysis snapshot
      description: 'Returns the latest precomputed alert-type rollup used to surface

        cost-trim opportunities (alert types that produce few or no customer

        escalations). The same base row set is rolled up at request time into

        one of several views (per-org, per-provider, per-type, etc.) so

        dashboards can request exactly the shape they need.


        Efficacy (`escalations / alerts`) is returned per row; bucketing of

        efficacy into named tiers is left to the UI.


        The snapshot is refreshed daily by a background scheduler; the `stale`

        field on the response indicates whether the latest snapshot is older

        than the configured freshness window.'
      parameters:
      - $ref: '#/components/parameters/user-id'
      - $ref: '#/components/parameters/organization-id'
      - $ref: '#/components/parameters/x-request-id'
      - name: view
        in: query
        description: 'Roll-up shape. Defaults to `org_provider_type` (raw rows). Other

          values produce server-side aggregations of the same base rows.

          '
        required: false
        schema:
          type: string
          enum:
          - org_provider_type
          - org_type
          - provider_type
          - org
          - provider
          - type
          - escalations_by_type
          default: org_provider_type
      - name: organization_id
        in: query
        description: 'Restrict the response to the given organization UUIDs. If omitted,

          all organizations the caller has access to via RBAC are included.

          Values are intersected with the accessible set server-side.

          '
        required: false
        schema:
          type: array
          items:
            type: string
        explode: true
      - name: provider
        in: query
        description: Case-insensitive exact-match filter on `alert_provider`.
        required: false
        schema:
          type: string
      - name: alert_type
        in: query
        description: Case-insensitive substring filter on `alert_type`.
        required: false
        schema:
          type: string
      - name: min_alerts
        in: query
        description: Drop rows whose total alert count is below this threshold.
        required: false
        schema:
          type: integer
          format: int64
          minimum: 0
      - name: escalation_thresholds
        in: query
        description: 'Comma-separated list of escalation-rate thresholds (0.0–1.0) used to

          compute the `trim_headroom` columns on the `org` view. Defaults to

          `0,0.05,0.10,0.25`.

          '
        required: false
        schema:
          type: string
      - name: limit
        in: query
        description: Maximum number of rows to return.
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 5000
          default: 500
      - name: offset
        in: query
        description: Row offset for pagination.
        required: false
        schema:
          type: integer
          minimum: 0
          default: 0
      security:
      - SessionCookie: []
      responses:
        '200':
          description: Cost-trim analysis snapshot fetched successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CostTrimAnalysisResponse'
        default:
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /investigation_tiers:
    get:
      tags:
      - Case Manager
      operationId: getInvestigationTiers
      summary: List investigation tiers per alert type for an organization
      description: 'Returns the investigation tier assigned to each (provider, alert type)

        the organization has cost-trim history for, including the 30-day alert

        volume and efficacy. The default tier is derived from investigation

        efficacy (escalations / alerts) by the cost-trim scheduler; a per-org

        override takes precedence when set. Powers the cost analysis tier table

        in the UI. Results can be sorted by provider, alert type, volume, or

        efficacy.'
      parameters:
      - $ref: '#/components/parameters/user-id'
      - $ref: '#/components/parameters/organization-id'
      - $ref: '#/components/parameters/x-request-id'
      - name: organization_id
        in: query
        required: true
        description: The organization to list investigation tiers for.
        schema:
          type: string
      - name: sort_by
        in: query
        required: false
        description: Field to sort rows by. Defaults to volume.
        schema:
          type: string
          enum:
          - alert_provider
          - alert_type
          - volume
          - efficacy
          default: volume
      - name: sort_order
        in: query
        required: false
        description: Sort direction. Defaults to desc.
        schema:
          type: string
          enum:
          - asc
          - desc
          default: desc
      security:
      - SessionCookie: []
      responses:
        '200':
          description: Investigation tiers listed successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvestigationTierListResponse'
        default:
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    patch:
      tags:
      - Case Manager
      operationId: updateInvestigationTiers
      summary: Override investigation tiers for one or more alert types
      description: 'Sets per-organization investigation tier overrides for one or more

        (provider, alert type) pairs in a single request. Each override takes

        precedence over the cost-trim-derived default tier until removed.'
      parameters:
      - $ref: '#/components/parameters/user-id'
      - $ref: '#/components/parameters/organization-id'
      - $ref: '#/components/parameters/x-request-id'
      security:
      - SessionCookie: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateInvestigationTiersRequest'
      responses:
        '200':
          description: Investigation tiers updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Success'
        default:
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /investigation_credits:
    get:
      tags:
      - Case Manager
      operationId: getInvestigationCredits
      summary: Get the weekly investigation credit balance for an organization
      description: 'Returns the current week''s investigation credit balance for an

        organization: the default allocation, credits rolled over from the prior

        week, credits used, and credits remaining. `limit_set` is false when the

        organization has no credit allocation configured (unlimited).'
      parameters:
      - $ref: '#/components/parameters/user-id'
      - $ref: '#/components/parameters/organization-id'
      - $ref: '#/components/parameters/x-request-id'
      - name: organization_id
        in: query
        required: true
        description: The organization to fetch the credit balance for.
        schema:
          type: string
      security:
      - SessionCookie: []
      responses:
        '200':
          description: Investigation credit balance fetched successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvestigationCreditsResponse'
        default:
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /investigation_credits/usage:
    get:
      tags:
      - Case Manager
      operationId: getInvestigationCreditUsage
      summary: List investigation credit usage for an organization
      description: 'Returns append-only credit ledger entries (charges, refunds, forfeits)

        for an organization over an optional time range, plus the total credits

        used. Powers the usage trend view in the UI.'
      parameters:
      - $ref: '#/components/parameters/user-id'
      - $ref: '#/components/parameters/organization-id'
      - $ref: '#/components/parameters/x-request-id'
      - name: organization_id
        in: query
        required: true
        description: The organization to fetch credit usage for.
        schema:
          type: string
      - name: from
        in: query
        required: false
        description: Unix epoch seconds; only entries created at or after this are returned.
        schema:
          type: integer
          format: int64
      - name: to
        in: query
        required: false
        description: Unix epoch seconds; only entries created at or before this are returned.
        schema:
          type: integer
          format: int64
      security:
      - SessionCookie: []
      responses:
        '200':
          description: Investigation credit usage fetched successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvestigationCreditUsageResponse'
        default:
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /case/soc/email:
    post:
      tags:
      - Case Manager
      operationId: emailSocPerformanceReportAPI
      summary: Email SOC Performance Report
      description: Queues SOC Performance Report email for delivery.
      parameters:
      - name: User-ID
        in: header
        description: The User ID of the requestor
        required: true
        schema:
          type: string
      - name: Organization-ID
        in: header
        description: The Organization ID associated with the requestor
        required: true
        schema:
          type: string
      - name: X-Request-ID
        in: header
        description: The ID associated with the request
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SocEmailRequest'
      responses:
        '200':
          description: Email queued for delivery
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SocEmailResponse'
        '400':
          description: Missing required fields
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        default:
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /case/analytics/email:
    post:
      tags:
      - Case Manager
      operationId: emailCaseAnalyticsReportAPI
      summary: Email Case Analytics Report
      description: Queues Case Analytics Report email for delivery.
      parameters:
      - name: User-ID
        in: header
        description: The User ID of the requestor
        required: true
        schema:
          type: string
      - name: Organization-ID
        in: header
        description: The Organization ID associated with the requestor
        required: true
        schema:
          type: string
      - name: X-Request-ID
        in: header
        description: The ID associated with the request
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CaseAnalyticsEmailRequest'
      responses:
        '200':
          description: Email queued for delivery
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CaseAnalyticsEmailResponse'
        '400':
          description: Missing required fields
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        default:
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /v1/actions:
    post:
      tags:
      - Case Manager
      operationId: listCaseActionsV1API
      summary: List case actions for an organization
      parameters:
      - $ref: '#/components/parameters/user-id'
      - $ref: '#/components/parameters/organization-id'
      - $ref: '#/components/parameters/x-request-id'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CaseActionsRequest'
      responses:
        '200':
          description: Case actions retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CaseActionsResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /v1/actions/recently_completed:
    post:
      tags:
      - Case Manager
      operationId: listRecentlyCompletedActionsAPI
      summary: List actions completed or marked will-not-do in the last 7 days
      parameters:
      - $ref: '#/components/parameters/user-id'
      - $ref: '#/components/parameters/organization-id'
      - $ref: '#/components/parameters/x-request-id'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CaseActionsRequest'
      responses:
        '200':
          description: Recently completed actions retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CaseActionsResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    CaseActionsSort:
      type: object
      required:
      - field
      - order
      properties:
        field:
          type: string
          enum:
          - action_severity
          - title
          - case_id
          - case_modified_at
          - status
          - assignee
          - required
          - priority
          - organization_code
          description: Field to sort results by
        order:
          $ref: '#/components/schemas/SortOrder'
          description: Sort direction
    OutlierCase:
      type: object
      required:
      - case_id
      - case_uuid
      properties:
        case_id:
          type: string
        case_uuid:
          type: string
        category:
          type: string
        severity:
          type: integer
        assignee_email:
          type: string
        investigation_time_seconds:
          type: integer
          description: Time from alert_acknowledged_at to investigation_completed_at in seconds.
        close_time_seconds:
          type: integer
          description: Time from alert_raised_at to case_closed_at in seconds.
    HostWidgets:
      type: object
      properties:
        repeat_incident_hosts:
          type: array
          items:
            $ref: '#/components/schemas/EntityCount'
          description: Hosts appearing in more than one case.
        hosts_in_malicious_activity:
          type: array
          items:
            $ref: '#/components/schemas/EntityCount'
          description: Hosts appearing in malicious cases.
        multi_vector_targeted_hosts:
          type: array
          items:
            $ref: '#/components/schemas/MultiVectorHost'
          description: Hosts involved in more than one distinct attack type.
    RemediationWidgets:
      type: object
      properties:
        unresolved_actions:
          type: array
          items:
            $ref: '#/components/schemas/CaseActionCount'
          description: Cases ranked by count of actions with status in [0,1,2] (New, Pending, Customer Pending).
        customer_action_cases:
          type: array
          items:
            $ref: '#/components/schemas/CaseActionCount'
          description: Cases ranked by count of actions with status=2 (Customer Pending).
    CaseSummaryField:
      type: object
      properties:
        executive_summary:
          type: string
        what_happened:
          type: string
        why_it_matters:
          type: string
        justification_for_decision:
          type: string
        who:
          type: string
        when:
          type: string
        reasons_for_concern:
          type: string
        reasons_for_close:
          type: string
        additional_context:
          type: string
        next_steps:
          type: string
        improvement_opportunities:
          type: string
        feedback:
          type: string
    CostTrimTotals:
      type: object
      required:
      - alerts
      - investigated
      - escalations
      - efficacy
      properties:
        alerts:
          type: integer
          format: int64
        investigated:
          type: integer
          format: int64
        escalations:
          type: integer
          format: int64
          description: Count of alerts whose linked case was escalated to the customer.
        efficacy:
          type: number
          format: double
          description: Total escalations divided by total alerts.
    CaseAnalyticsEmailRequest:
      type: object
      required:
      - email_ids
      - subject
      - filter
      properties:
        email_ids:
          type: array
          items:
            type: string
          description: List of email addresses to send the report to
        subject:
          type: string
          description: Email subject line. If empty, a default subject will be generated.
        filter:
          $ref: '#/components/schemas/CaseAnalyticsEmailRequestFilter'
          description: Filter parameters for the report
    MetricsAttributes:
      required:
      - mean_metric_total
      - daily_mean_metrics
      - mean_metrics_intervals
      type: object
      properties:
        mean_metric_total:
          type: number
          description: Mean metric value for the total range
        daily_mean_metrics:
          type: object
          additionalProperties:
            type: number
          description: Mean metric values for each day
        mean_metrics_intervals:
          type: object
          additionalProperties:
            type: number
          description: Mean metric values for each interval
    SocPerformanceDashboardResponse:
      type: object
      required:
      - message
      - data
      properties:
        message:
          type: string
        data:
          $ref: '#/components/schemas/SocPerformanceDashboardData'
    UserDetail:
      type: object
      required:
      - firstname
      - user_uuid
      - email
      properties:
        firstname:
          type: string
        lastname:
          type: string
        email:
          type: string
        user_uuid:
          type: string
    AlertTypeCount:
      type: object
      required:
      - alert_type
      - total
      properties:
        alert_type:
          type: string
        total:
          type: integer
          description: Total cases for this alert type.
        malicious:
          type: integer
          description: Cases with disposition=10 (Malicious).
        false_positive:
          type: integer
          description: Cases with disposition in [1,5] (NoThreatFound + NonMaliciousPositive).
    DetectionWidgets:
      type: object
      properties:
        high_value_detections:
          type: array
          items:
            $ref: '#/components/schemas/AlertTypeCount'
          description: Alert types ranked by malicious case count.
        false_positive_alert_types:
          type: array
          items:
            $ref: '#/components/schemas/AlertTypeCount'
          description: Alert types ranked by false positive case count.
        uninvestigated_alerts:
          type: array
          items:
            $ref: '#/components/schemas/AlertTypeCount'
          description: Alert types with no linked case (linked_case_id null and no non-empty case_id in linked_case_executions).
        missing_data:
          type: array
          items:
            $ref: '#/components/schemas/AlertTypeCount'
          description: Alert types where cases have a non-empty confidence.missing_information field, grouped by alert type.
        top_alert_types:
          type: array
          items:
            $ref: '#/components/schemas/AlertTypeCount'
          description: Top 10 alert types ranked by case count within the requested date range.
    UpdateCaseResponse:
      type: object
      required:
      - message
      - data
      properties:
        message:
          type: string
        data:
          $ref: '#/components/schemas/CaseDetails'
          description: updated case object
    ScoringGuidelines:
      type: object
      required:
      - id
      - scoring_criteria
      - guidelines_text
      properties:
        id:
          type: string
        is_organization_default:
          type: boolean
          description: If true, the scoring guidelines will be set as the default scoring guidelines for the organization.
        organization_id:
          type: string
          description: Organization id of the organization the scoring guidelines belongs to.
        is_global_default:
          type: boolean
          description: If true, the scoring guidelines will be set as the default scoring guidelines for all organizations.
        name:
          type: string
        version:
          type: integer
        guidelines_text:
          type: string
        scoring_criteria:
          type: object
          description: map of scoring criteria
          additionalProperties:
            type: number
            format: double
    ProviderSummary:
      type: object
      required:
      - name
      - display_name
      - logo_url
      - provider_id
      properties:
        name:
          type: string
        display_name:
          type: string
        logo_url:
          type: string
        provider_id:
          type: string
    CaseMetricsResponse:
      type: object
      required:
      - message
      - data
      properties:
        message:
          type: string
        data:
          $ref: '#/components/schemas/CaseMetrics'
          description: case metrics object
    CostTrimSnapshotRow:
      type: object
      required:
      - organization_uuid
      - alert_provider
      - alert_type
      - alerts
      - investigated
      - escalated_to_customer
      properties:
        organization_uuid:
          type: string
        organization_code:
          type: string
        alert_provider:
          type: string
        alert_type:
          type: string
        window_start:
          type: integer
          format: int64
        window_end:
          type: integer
          format: int64
        computed_at:
          type: integer
          format: int64
        alerts:
          type: integer
          format: int64
        investigated:
          type: integer
          format: int64
        linked_case_count:
          type: integer
          format: int64
        escalated_to_customer:
          type: integer
          format: int64
        escalated_to_analyst:
          type: integer
          format: int64
        first_seen_at:
          type: integer
          format: int64
        last_seen_at:
          type: integer
          format: int64
    UserWidgets:
      type: object
      properties:
        repeat_targeted_users:
          type: array
          items:
            $ref: '#/components/schemas/EntityCount'
          description: Users (type=user or service_account) appearing in more than one case.
        users_in_malicious_activity:
          type: array
          items:
            $ref: '#/components/schemas/EntityCount'
          description: Users appearing in malicious cases (disposition=10).
        users_high_false_positives:
          type: array
          items:
            $ref: '#/components/schemas/EntityCount'
          description: Users most frequently appearing in non-malicious cases (disposition in [1,5]).
        multi_vector_targeted_users:
          type: array
          items:
            $ref: '#/components/schemas/MultiVectorUser'
          description: Users involved in more than one distinct attack type.
    InvestigationTierRow:
      type: object
      required:
      - alert_provider
      - alert_type
      - volume
      - default_tier
      - investigation_tier
      - overridden
      properties:
        alert_provider:
          type: string
        alert_type:
          type: string
        volume:
          type: integer
          format: int64
          description: number of alerts of this type over the cost-trim window (30d)
        default_tier:
          type: string
          description: tier derived from efficacy by the cost-trim scheduler
        investigation_tier:
          type: string
          description: effective tier (override if present, otherwise default_tier)
        overridden:
          type: boolean
        efficacy:
          type: number
          format: double
          description: escalations / alerts over the cost-trim window (0..1)
        model:
          type: string
          description: model backing the effective tier
        cost:
          type: number
          format: double
          description: credit cost per investigation at the effective tier
    CreateCaseResponse:
      type: object
      required:
      - message
      - data
      properties:
        message:
          type: string
        data:
          $ref: '#/components/schemas/CaseDetails'
          description: created case object
    ResponseRemediationWidgets:
      type: object
      properties:
        stalled_cases_count:
          type: integer
          description: Number of cases currently in status=10 (CustomerPending).
        stalled_cases_by_category:
          type: array
          items:
            $ref: '#/components/schemas/CategoryCount'
          description: Stalled case count (status=10) grouped by case category.
        customer_response_time:
          $ref: '#/components/schemas/ResponseTimeMetric'
          description: 'Avg time from customer_pending_at to customer_responded_at. Requires two new timestamp fields on CaseTimeline: customer_pending_at (set on status→10) and customer_responded_at (set on first customer activity — comment, field change, or action update).'
    InvestigationCreditUsageResponse:
      type: object
      required:
      - entries
      - total_used
      properties:
        total_used:
          type: number
          format: double
        entries:
          type: array
          items:
            $ref: '#/components/schemas/CreditUsageEntry'
    EntityCount:
      type: object
      required:
      - name
      - case_count
      properties:
        name:
          type: string
          description: Entity value (e.g. IP address, domain, username, hostname).
        entity_type:
          type: string
          description: Entity type (ip, domain, user, service_account, host, file_hash, cloud_resource).
        case_count:
          type: integer
          description: Number of distinct cases this entity appears in.
    CaseActionCount:
      type: object
      required:
      - case_id
      - count
      properties:
        case_id:
          type: string
        count:
          type: integer
          description: Number of actions matching the filter for this case.
    CaseActionListItem:
      type: object
      properties:
        uuid:
          type: string
          description: Unique identifier of the action
        title:
          type: string
          description: Action title (markdown text)
        status:
          type: integer
          description: Action status value
        status_label:
          type: string
          description: Human-readable label for the status
        action_severity:
          $ref: '#/components/schemas/ActionSeverityLevel'
        assignee:
          $ref: '#/components/schemas/UserDetails'
        assignee_v2:
          $ref: '#/components/schemas/AssigneeDetails'
          description: AssigneeDetails for the action; populated alongside assignee during migration
        case_id:
          type: string
          description: Human-readable case identifier
        case_uuid:
          type: string
          description: UUID of the parent case
        organization_id:
          type: string
          description: UUID of the organization the parent case belongs to
        organization_code:
          type: string
          description: Code of the organization the parent case belongs to
        case_modified_at:
          type: integer
          format: int64
          description: Unix epoch seconds when the parent case was last modified
        created_at:
          type: integer
          format: int64
          description: Unix epoch seconds when the action was created
        modified_at:
          type: integer
          format: int64
          description: Unix epoch seconds when the action was last modified
        completed_at:
          type: integer
          format: int64
          description: Unix epoch seconds when the action was completed or marked will-not-do; 0 if not terminal
        required:
          type: boolean
          description: Whether this action is required
        description:
          type: string
          description: Description of the action required
        session_id:
          type: string
          description: Chat session ID associated with the action
        type:
          type: string
          enum:
          - approval
          - customer_action
          - answer_question
          description: Type of action; null is treated as customer_action
        blocking_reason:
          type: string
          description: Reason this action is blocking the case; only set when type is customer_action
        blocking_fact_id:
          type: string
          description: ID of the fact this action is blocking; only set when type is customer_action
        playbook_id:
          type: string
          description: ID of the playbook associated with this action; only set when type is approval
        priority:
          type: string
          enum:
          - Containment
          - Required
          - Recommended
          description: Priority of the action; when set on create/update, the required flag is derived from it (Containment/Required -> true, Recommended -> false)
        evidences:
          type: array
          items:
            type: string
          description: Free-form evidence text snippets associated with the action
        status_v2:
          $ref: '#/components/schemas/ActionStatusV2'
          description: Lifecycle status of the action, kept in sync with status. If both status and status_v2 are set on write, status_v2 takes priority and status is derived from it. For type approval/answer_question, only completed/will_not_do may be set directly; customer_action allows all values.
        execution_details:
          $ref: '#/components/schemas/ActionExecutionDetails'
          description: Details of the playbook execution triggered externally for this action; only set when type is approval. Polled until the execution reaches a terminal state, at which point status_v2/type are updated accordingly.
        is_agentic_case:
          type: boolean
          description: Whether the parent case was created by agentic investigation
    CostTrimOrgTypeRow:
      allOf:
      - $ref: '#/components/schemas/CostTrimRollupBase'
      - type: object
        required:
        - organization_uuid
        - alert_type
        properties:
          organization_uuid:
            type: string
          organization_code:
            type: string
          alert_type:
            type: string
    GetScoringGuidelinesResponse:
      type: object
      required:
      - message
      - data
      properties:
        message:
          type: string
        data:
          $ref: '#/components/schemas/ScoringGuidelines'
          description: scoring guidelines object
    ArchiveCasesRequest:
      type: object
      required:
      - case_uuids
      properties:
        case_uuids:
          type: array
          items:
            type: string
          description: list of case uuids to be archived
        performed_by_darryl:
          type: boolean
    CreateCaseRequest:
      type: object
      required:
      - name
      properties:
        name:
          type: string
          description: Title to be set for the case
        organization_id:
          type: string
          description: Identifier (uuid or org code) of the organization associated with the case
        type:
          $ref: '#/components/schemas/CaseType'
        status:
          $ref: '#/components/schemas/CaseStatus'
        severity:
          $ref: '#/components/schemas/CaseSeverity'
        priority:
          $ref: '#/components/schemas/CasePriority'
        assignee:
          type: string
          description: Uuid of the assigned user
        assignee_email:
          type: string
          description: Email of the assigned user
        performed_by_darryl:
          type: boolean
        alert_source:
          $ref: '#/components/schemas/AlertSource'
        alert_category:
          $ref: '#/components/schemas/AlertCategory'
        alert_created_at:
          type: integer
          description: Creation time of alert in seconds/epoch time.
        disposition:
          $ref: '#/components/schemas/CaseDisposition'
        escalated_to_customer:
          type: boolean
        case_summary_fields:
          $ref: '#/components/schemas/CaseSummaryField'
          description: Case summary object
        linked_sessions:
          type: array
          items:
            type: string
          description: Linked sessions with the case
        linked_alerts:
          type: array
          items:
            type: string
          description: Linked alerts with the case
        categories:
          type: array
          items:
            type: string
          description: Values indicating the categories assigned to case.
        sub_categories:
          type: array
          items:
            type: string
          description: Values indicating the sub categories assigned to case.
    MultiVectorHost:
      type: object
      required:
      - name
      - attack_types
      properties:
        name:
          type: string
          description: Hostname.
        attack_types:
          type: array
          items:
            $ref: '#/components/schemas/AttackTypeCount'
          description: Distinct alert types this host has been involved in, with case count per type.
        case_count:
          type: integer
    CustomerExperienceWidgets:
      type: object
      properties:
        cases_with_communication_count:
          type: integer
          description: Cases with at least one escalation entry where escalated_to=0 (EscalatedToCustomer). Escalation is the confirmed trigger for customer notification tracking.
        escalation_breakdown:
          $ref: '#/components/schemas/EscalationBreakdown'
          description: Overall breakdown of escalated vs non-escalated cases.
        communication_by_severity:
          type: array
          items:
            $ref: '#/components/schemas/CommunicationBySeverity'
          description: For each severity, count of cases with and without customer communication.
        communication_by_disposition:
          type: array
          items:
            $ref: '#/components/schemas/CommunicationByDisposition'
          description: For each disposition, count of cases with and without customer communication.
    CaseActionsRequest:
      type: object
      required:
      - pagination
      - sort
      properties:
        pagination:
          type: object
          required:
          - page
          - size
          properties:
            page:
              type: integer
              description: 0-indexed page number
            size:
              type: integer
              description: Number of results per page
        sort:
          $ref: '#/components/schemas/CaseActionsSort'
        filter:
          $ref: '#/components/schemas/CaseActionsFilter'
    TrendWidgets:
      type: object
      properties:
        cases_over_time:
          type: array
          items:
            $ref: '#/components/schemas/DailyCount'
          description: Daily case volume within the requested date range.
        cases_by_severity:
          type: array
          items:
            $ref: '#/components/schemas/SeverityCount'
          description: Case count broken down by severity level.
        business_hours_breakdown:
          $ref: '#/components/schemas/BusinessHoursBreakdown'
          description: Case volume split by business hours (Mon–Fri 09:00–17:00 UTC) vs after-hours & weekends.
    ResponseTimePercentiles:
      type: object
      properties:
        mtta:
          $ref: '#/components/schemas/PercentileMetric'
        mtti:
          $ref: '#/components/schemas/PercentileMetric'
        mttc:
          $ref: '#/components/schemas/PercentileMetric'
        mtt_close:
          $ref: '#/components/schemas/PercentileMetric'
    CaseDetails:
      type: object
      required:
      - case_id
      - case_uuid
      - organization_id
      - name
      - type
      - status
      - severity
      - priority
      - assignee
      - reporter
      - alert_source
      - alert_category
      - created_at
      - modified_at
      - case_summary_fields
      - case_link
      properties:
        case_id:
          type: string
          description: Unique number respresenting case of an organization
        case_uuid:
          type: string
          description: Unique identifier of case
        organization_id:
          type: string
          description: Identifier of the organization associated with the case
        name:
          type: string
          description: Title of the case
        type:
          $ref: '#/components/schemas/CaseType'
        status:
          $ref: '#/components/schemas/CaseStatus'
        severity:
          $ref: '#/components/schemas/CaseSeverity'
        priority:
          $ref: '#/components/schemas/CasePriority'
        assignee:
          $ref: '#/components/schemas/UserDetails'
        reporter:
          $ref: '#/components/schemas/UserDetails'
        alert_source:
          $ref: '#/components/schemas/AlertSource'
        alert_category:
          $ref: '#/components/schemas/AlertCategory'
        disposition:
          $ref: '#/components/schemas/CaseDisposition'
        archived:
          type: boolean
          description: Flag indicating if the case has been archived or not
        escalated_to_customer:
          type: boolean
        created_at:
          type: integer
          format: int64
          description: Timestamp of creation of the case.
        modified_at:
          type: integer
          format: int64
          description: Timestamp of the last modification of the case.
        alert_created_at:
          type: integer
          format: int64
          description: Timestamp of alert linked to the case.
        case_summary_fields:
          $ref: '#/components/schemas/CaseSummaryField'
          description: Case summary object
        linked_sessions:
          type: array
          items:
            $ref: '#/components/schemas/ChatSessionDetail'
          description: Linked sessions with the case
        linked_alerts:
          type: array
          items:
            type: string
          description: Linked alerts with the case
        linked_cases:
          type: array
          items:
            $ref: '#/components/schemas/Case'
          description: Other linked cases with the case
        categories:
          type: array
          items:
            type: string
          description: Values indicating the categories assigned to case
        sub_categories:
          type: array
          items:
            type: string
          description: Values indicating the sub categories assigned to case
        case_link:
          type: string
          description: link to the case manager
    SocPerformanceDashboardData:
      type: object
      properties:
        kpi:
          $ref: '#/components/schemas/KpiWidgets'
        speed_sla:
          $ref: '#/components/schemas/SpeedSlaWidgets'
        throughput:
          $ref: '#/components/schemas/ThroughputWidgets'
        investigation_quality:
          $ref: '#/components/schemas/InvestigationQualityWidgets'
        response_remediation:
          $ref: '#/components/schemas/ResponseRemediationWidgets'
        consistency:
          $ref: '#/components/schemas/ConsistencyWidgets'
        customer_experience:
          $ref: '#/components/schemas/CustomerExperienceWidgets'
        automation:
          $ref: '#/components/schemas/AutomationWidgets'
        operational_gaps:
          $ref: '#/components/schemas/OperationalGapsWidgets'
    BulkDeleteCasesRequest:
      type: object
      required:
      - case_uuids
      properties:
        case_uuids:
          type: array
          items:
            type: string
    CasePriority:
      type: integer
      enum:
      - 0
      - 10
      - 20
      - 30
      x-enum-varnames:
      - LowCasePriority
      - MediumCasePriority
      - HighCasePriority
      - CriticalCasePriority
    ScoreStatus:
      type: string
      enum:
      - not_generated
      - in_progress
      - completed
      x-enum-varnames:
      - ScoreStatusNotGenerated
      - ScoreStatusInProgress
      - ScoreStatusCompleted
    CreditUsageEntry:
      type: object
      required:
      - week_start
      - amount
      - reason
      - created_at
      properties:
        week_start:
          type: string
        alert_id:
          type: string
        tier:
          type: string
        model:
          type: string
        amount:
          type: number
          format: double
          description: negative for charges/forfeits, positive for refunds
        reason:
          type: string
        created_at:
          type: integer
          format: int64
    CaseDisposition:
      type: integer
      enum:
      - 0
      - 1
      - 2
      - 3
      x-enum-varnames:
      - Pending
      - TruePositive
      - BenignTruePositive
      - FalsePositive
    DailyCount:
      type: object
      required:
      - date
      - count
      properties:
        date:
          type: string
          description: Date in YYYY-MM-DD format.
        count:
          type: integer
    SocEmailRequestFilter:
      type: object
      required:
      - created_at_from
      - created_at_to
      properties:
        org_id:
          type: string
          description: Organization identifier (UUID or org code). If not provided, uses the Organization-ID header value
        created_at_from:
          type: integer
          format: int64
          description: Unix epoch seconds (start of date range)
        created_at_to:
          type: integer
          format: int64
          description: Unix epoch seconds (end of date range)
        metadata:
          type: object
          description: Optional metadata for report customization
    AlertCategory:
      type: integer
      enum:
      - 0
      x-enum-varnames:
      - ManualAlertCategory
    GenerateCaseScoreResponse:
      type: object
      required:
      - message
      - data
      properties:
        message:
          type: string
        data:
          $ref: '#/components/schemas/CaseScore'
          description: case score object
    CostTrimOrgRow:
      allOf:
      - $ref: '#/components/schemas/CostTrimRollupBase'
      - type: object
        required:
        - organization_uuid
        - alert_types
        properties:
          organization_uuid:
            type: string
          organization_code:
            type: string
          alert_types:
            type: integer
            description: Count of distinct alert types within this org.
          trim_headroom:
            type: object
            additionalProperties:
              type: number
              format: double
            description: 'Map of threshold-name → fraction of total alerts in this org

              that come from alert types with escalation rate ≤ threshold.

              Keys are named `safe_trim_pct_0` for 0% and `trim_pct_N` for

              N% (e.g. `trim_pct_5`, `trim_pct_10`, `trim_pct_25`).

              '
    GetDetailedMetricsResponse:
      type: object
      required:
      - message
      - data
      properties:
        message:
          type: string
        data:
          $ref: '#/components/schemas/AggregatedMetrics'
    CaseFilter:
      type: object
      properties:
        severity:
          type: array
          items:
            $ref: '#/components/schemas/CaseSeverity'
        status:
          type: array
          items:
            $ref: '#/components/schemas/CaseStatus'
        priority:
          type: array
          items:
            $ref: '#/components/schemas/CasePriority'
        case_id:
          type: string
        name:
          type: string
        description:
          type: string
        reporter:
          type: array
          items:
            type: string
        assignee:
          type: array
          items:
            type: string
        from_modified_date:
          type: integer
          format: int64
        to_modified_date:
          type: integer
          format: int64
        global_search_query:
          type: string
          deprecated: true
        queries:
          type: array
          description: list of queries to search for in all fields. A case will be listed if it matches any of the queries
          items:
            type: string
        archived:
          type: boolean
          description: Flag indicating if archived cases has to be searched or not
    AdrTriageDailyBreakdown:
      type: object
      required:
      - date
      properties:
        date:
          type: string
          description: Date in YYYY-MM-DD format.
        fully_automated:
          type: integer
        partially_automated:
          type: integer
        manual:
          type: integer
    SpeedSlaWidgets:
      type: object
      properties:
        mtta:
          $ref: '#/components/schemas/ResponseTimeMetric'
          description: 'Mean Time to Acknowledge: avg(alert_acknowledged_at - alert_raised_at).'
        mtti:
          $ref: '#/components/schemas/ResponseTimeMetric'
          description: 'Mean Time to Investigate: avg(investigation_completed_at - alert_acknowledged_at).'
        mttc:
          $ref: '#/components/schemas/ResponseTimeMetric'
          description: 'Mean Time to Contain: avg(case_contained_at - alert_raised_at).'
        mtt_close:
          $ref: '#/components/schemas/ResponseTimeMetric'
          description: 'Mean Time to Close: avg(case_closed_at - alert_raised_at).'
        sla_config:
          $ref: '#/components/schemas/SlaConfig'
          description: SLA targets echoed in response for UI display.
        critical_incident_adherence:
          $ref: '#/components/schemas/SlaAdherenceResult'
          description: SLA adherence for Critical Incident Support (sev=15, target=2hr).
        critical_alert_adherence:
          $ref: '#/components/schemas/SlaAdherenceResult'
          description: SLA adherence for Critical Alert Validation (sev=10, target=4hr).
        non_critical_adherence:
          $ref: '#/components/schemas/SlaAdherenceResult'
          description: SLA adherence for Non-Critical Incident Support (sev≤5, target=8hr).
        sla_adherence_trend:
          type: array
          items:
            $ref: '#/components/schemas/SlaAdherenceTrendPoint'
          description: Daily SLA adherence % for all 3 tiers — three line charts over the date window.
        response_time_percentiles:
          $ref: '#/components/schemas/ResponseTimePercentiles'
          description: P50/P95/P99 for each timing metric across closed cases in the window.
    CaseAnalyticsDashboardResponse:
      type: object
      required:
      - message
      - data
      properties:
        message:
          type: string
        data:
          $ref: '#/components/schemas/CaseAnalyticsDashboardData'
    CreateScoringGuidelinesResponse:
      type: object
      required:
      - message
      - data
      properties:
        message:
          type: string
        data:
          $ref: '#/components/schemas/ScoringGuidelines'
          description: scoring guidelines object
    SlaAdherenceResult:
      type: object
      required:
      - total_cases
      - met_count
      - breach_count
      - adherence_pct
      properties:
        total_cases:
          type: integer
        met_count:
          type: integer
          description: Cases where investigation_completed_metric <= target.
        breach_count:
          type: integer
          description: Cases where investigation_completed_metric > target.
        adherence_pct:
          type: number
          format: float
          description: met_count / total_cases as a percentage.
        avg_mtti_seconds:
          type: integer
          description: Average MTTI across all cases in this tier.
    QuestionsAnsweredByCategory:
      type: object
      description: Answered vs unanswered question split across the 3 question categories. Used for grouped bar chart.
      properties:
        investigation_questions:
          $ref: '#/components/schemas/QuestionsAnsweredSplit'
          description: case_detail_fields.custom_questions[]
        faqs:
          $ref: '#/components/schemas/QuestionsAnsweredSplit'
          description: case_detail_fields.faqs[]
        explore_deeper:
          $ref: '#/components/schemas/QuestionsAnsweredSplit'
          description: case_detail_fields.explore_deeper_questions[]
    OrganizationMetrics:
      allOf:
      - $ref: '#/components/schemas/DetailedMetrics'
      - type: object
        required:
        - organization_id
        properties:
          organization_id:
            type: string
            description: Organization ID
    ProviderMetrics:
      allOf:
      - $ref: '#/components/schemas/Metrics'
      - type: object
        required:
        - provider
        properties:
          provider:
            $ref: '#/components/schemas/ProviderSummary'
          alert_type_metrics_list:
            type: array
            items:
              $ref: '#/components/schemas/AlertTypeMetrics'
            description: Alert type metrics list
    InvestigationTierListResponse:
      type: object
      required:
      - tiers
      properties:
        tiers:
          type: array
          items:
            $ref: '#/components/schemas/InvestigationTierRow'
    CaseMetricsSummaryResponse:
      type: object
      required:
      - message
      - summary
      properties:
        message:
          type: string
          description: Message indicating the status of the summary generation.
        summary:
          type: array
          items:
            $ref: '#/components/schemas/CaseMetricsLLMSummary'
          description: A summary of the case metrics in natural language generated by Darryl using the available case data and metrics. This summary can be used to quickly understand the overall status and health of the case.
    CostTrimProviderTypeRow:
      allOf:
      - $ref: '#/components/schemas/CostTrimRollupBase'
      - type: object
        required:
        - alert_provider
        - alert_type
        properties:
          alert_provider:
            type: string
          alert_type:
            type: string
    SlaAdherenceTrendPoint:
      type: object
      required:
      - date
      properties:
        date:
          type: string
          description: Date in YYYY-MM-DD format.
        critical_incident_pct:
          type: number
          format: float
          description: SLA adherence % for Critical Incident Support (sev=15, target=2hr) on this day.
        critical_alert_pct:
          type: number
          format: float
          description: SLA adherence % for Critical Alert Validation (sev=10, target=4hr) on this day.
        non_critical_pct:
          type: number
          format: float
          description: SLA adherence % for Non-Critical Incident Support (sev≤5, target=8hr) on this day.
    CommunicationBySeverity:
      type: object
      required:
      - severity
      - with_communication
      - without_communication
      properties:
        severity:
          type: integer
        severity_label:
          type: string
        with_communication:
          type: integer
        without_communication:
          type: integer
    GetCaseScoreResponse:
      type: object
      required:
      - message
      - data
      properties:
        message:
          type: string
        data:
          $ref: '#/components/schemas/CaseScore'
          description: case score object
    CaseView:
      type: integer
      enum:
      - 0
      - 1
      x-enum-varnames:
      - CustomerCaseView
      - AnalystCaseView
    CaseReviewMetrics:
      type: object
      properties:
        case_coverage:
          type: number
          format: double
        darryl_investigated_case_coverage:
          type: number
          format: double
        human_investigated_case_coverage:
          type: number
          format: double
        cases_to_be_reviewed:
          type: integer
          description: Number of cases to be reviewed
        cases_reviewed:
          type: integer
          description: Number of cases reviewed
        high_quality_cases:
          type: integer
          description: Number of high quality cases
        medium_quality_cases:
          type: integer
          description: Number of medium quality cases
        low_quality_cases:
          type: integer
          description: Number of low quality cases
        case_quality:
          type: number
          format: double
        darryl_investigated_case_quality:
          type: number
          format: double
        human_investigated_case_quality:
          type: number
          format: double
    CaseMetrics:
      type: object
      required:
      - total_cases
      - mean_time_to_ack
      - mean_time_to_contain
      - mean_time_to_close
      - handled_by_darryl
      - sub_category_count_darryl
      - status_count
      - severity_count
      - escalated_to_customer_count
      - case_count_per_day
      properties:
        total_cases:
          type: integer
          description: total cases covered in analysis
        mean_time_to_ack:
          $ref: '#/components/schemas/MetricsAttributes'
          description: mtta metrics
        mean_time_to_investigate:
          $ref: '#/components/schemas/MetricsAttributes'
          description: mtti metrics
        mean_time_to_contain:
          $ref: '#/components/schemas/MetricsAttributes'
          description: mttr metrics
        mean_time_to_close:
          $ref: '#/components/schemas/MetricsAttributes'
          description: mttc metrics
        handled_by_darryl:
          type: integer
          description: cases handled by darryl out of all cases
        sub_category_count_darryl:
          type: object
          additionalProperties:
            type: integer
          description: Top-10 sub cateogries by count for cases handled by darryl
        status_count:
          type: object
          additionalProperties:
            type: integer
          description: count of cases for each status type
        severity_count:
          type: object
          additionalProperties:
            type: integer
          description: count of cases for each severity type
        escalated_to_customer_count:
          type: integer
          description: number of cases escalated to customer
        case_count_per_day:
          type: object
          additionalProperties:
            type: integer
            format: int64
          description: count of cases for each severity type
    CreateScoringGuidelinesRequest:
      type: object
      required:
      - guidelines_text
      - scoring_criteria
      properties:
        is_organization_default:
          type: boolean
          description: If true, the scoring guidelines will be set as the default scoring guidelines for the organization.
        name:
          type: string
        guidelines_text:
          type: string
        scoring_criteria:
          type: object
          description: map of scoring criteria
          additionalProperties:
            type: number
            format: double
    UpdateCaseRequest:
      type: object
      properties:
        name:
          type: string
          description: Title to be set for the case
        status:
          $ref: '#/components/schemas/CaseStatus'
        severity:
          $ref: '#/components/schemas/CaseSeverity'
        priority:
          $ref: '#/components/schemas/CasePriority'
        assignee:
          type: string
          description: Uuid of the assigned user
        assignee_email:
          type: string
          description: Email of the assigned user
        disposition:
          $ref: '#/components/schemas/CaseDisposition'
        archived:
          type: boolean
          description: Unarchive case if it's archived. (no change if its true)
        escalated_to_customer:
          type: boolean
        performed_by_darryl:
          type: boolean
        case_summary_fields:
          $ref: '#/components/schemas/CaseSummaryField'
          description: Case summary object
        replace_case_summary:
          type: boolean
          description: If this field is true, case summary will be replace. Otherwise, it will append to previously existing value.
        append_mode:
          description: Specify how to append data to existing one. Use 0 for new line, 1 for space.
          $ref: '#/components/schemas/AppendMode'
        categories:
          type: array
          items:
            type: string
          description: Values indicating the categories assigned to case. List wil be replaced.
        sub_categories:
          type: array
          items:
            type: string
          description: Values indicating the sub categories assigned to case. List wil be replaced.
    ActionStatusV2:
      type: string
      enum:
      - open
      - in_progress
      - blocked
      - completed
      - will_not_do
      description: 'Lifecycle status of an action, kept in sync with status. Mapping from status: 0/New -> open, 1/Pending -> in_progress, 2/Customer Pending -> blocked, 3/Approved -> in_progress, 4/Rejected -> will_not_do, 5/Completed -> completed.'
    CostTrimEscalationsByTypeRow:
      type: object
      required:
      - alert_type
      - escalations
      properties:
        alert_type:
          type: string
        escalations:
          type: integer
          format: int64
    MissingTelemetryCount:
      type: object
      required:
      - alert_type
      - case_count
      properties:
        alert_type:
          type: string
        case_count:
          type: integer
          description: Cases where confidence.missing_information is non-empty.
    CaseListResponse:
      type: object
      required:
      - message
      - data
      - total
      properties:
        message:
          type: string
        data:
          type: array
          items:
            $ref: '#/components/schemas/Case'
          description: list of minimal case objects
        total:
          type: integer
    AlertTypeMetrics:
      allOf:
      - $ref: '#/components/schemas/Metrics'
      - type: object
        required:
        - provider
        - alert_type
        properties:
          provider:
            $ref: '#/components/schemas/ProviderSummary'
          alert_type:
            type: string
          severity_metrics_list:
            type: array
            items:
              $ref: '#/components/schemas/SeverityMetrics'
              description: Severity metrics list
    InvestigationQualityWidgets:
      type: object
      properties:
        questions_per_category:
          $ref: '#/components/schemas/QuestionsAnsweredByCategory'
          description: Answered vs unanswered question counts across 3 categories. Grouped bar chart.
        escalations_by_severity:
          type: array
          items:
            $ref: '#/components/schemas/SeverityCount'
          description: Escalated case count grouped by severity.
        rework_daily:
          type: array
          items:
            $ref: '#/components/schemas/ReworkDailyPoint'
          description: Daily reinvestigation count, rate, and avg time to rework.
        quality_score_daily:
          type: array
          items:
            $ref: '#/components/schemas/QualityScoreDailyPoint'
          description: Daily avg quality score — three line charts (overall, Darryl, human).
        questions_answered_by_outcome:
          type: array
          items:
            $ref: '#/components/schemas/QuestionsAnsweredByOutcome'
          description: Count of answered explore_deeper_questions grouped by case disposition (outcome).
    CaseStatus:
      type: integer
      enum:
      - 0
      - 1
      - 5
      - 10
      - 20
      - 30
      x-enum-varnames:
      - NewCaseStatus
      - ProgressCaseStaus
      - PendingCaseStaus
      - WaitingForCustomerStatus
      - ContainedCaseStaus
      - ClosedCaseStaus
    SlaConfig:
      type: object
      description: 'Three SLA tiers. Critical Incident Support (sev=15): 2hr MTTI for true incidents (malware, lateral movement). Critical Alert Validation (sev=10): 4hr MTTI for critical alert detection and customer notification. Non-Critical (sev≤5): 8hr MTTI for incidents with mitigations in place.'
      properties:
        critical_incident_target_seconds:
          type: integer
          default: 7200
          description: MTTI target for Critical severity (sev=15) true incidents — 2 hr.
        critical_alert_target_seconds:
          type: integer
          default: 14400
          description: MTTI target for High severity (sev=10) alert validation and customer notification — 4 hr.
        non_critical_target_seconds:
          type: integer
          default: 28800
          description: MTTI target for non-critical severity (sev≤5) incidents — 8 hr.
    CaseSort:
      type: object
      required:
      - field
      - sort_order
      properties:
        field:
          type: string
          description: indicates which field will be used for sorting
        sort_order:
          $ref: '#/components/schemas/SortOrder'
          description: indicates sort order - asc or desc
    CaseLinkRequest:
      type: object
      required:
      - case_uuids
      properties:
        case_uuids:
          type: array
          items:
            type: string
    DailyMetrics:
      type: object
      required:
      - date
      - provider_list
      properties:
        date:
          type: string
        provider_list:
          type: array
          items:
            $ref: '#/components/schemas/ProviderList'
          description: Provider list
    CostTrimProviderRow:
      allOf:
      - $ref: '#/components/schemas/CostTrimRollupBase'
      - type: object
        required:
        - alert_provider
        properties:
          alert_provider:
            type: string
    EscalationBreakdown:
      type: object
      required:
      - escalated_count
      - not_escalated_count
      - total
      properties:
        escalated_count:
          type: integer
          description: Number of cases with at least one escalation in the escalations[] array.
        not_escalated_count:
          type: integer
          description: Number of cases with no escalations.
        total:
          type: integer
          description: Total case count (escalated_count + not_escalated_count).
        ai_summary:
          type: string
          description: AI-generated natural-language summary of the escalation breakdown. Populated separately; may be absent.
    EntityCountWithDays:
      allOf:
      - $ref: '#/components/schemas/EntityCount'
      - type: object
        required:
        - days
        properties:
          days:
            type: integer
            description: Number of distinct days this entity appears in cases.
    TimeRange:
      type: object
      properties:
        from_date:
          type: integer
          format: int64
        to_date:
          type: integer
          format: int64
    CaseAnalyticsEmailResponse:
      type: object
      required:
      - message
      properties:
        message:
          type: string
          description: Status message confirming email was queued
    EmergingThreat:
      type: object
      required:
      - category
      - current_count
      - prior_count
      properties:
        category:
          type: string
        current_count:
          type: integer
          description: Case count in the current window.
        prior_count:
          type: integer
          description: Case count in the prior equal window.
        growth_rate:
          type: number
          format: float
          description: Growth as a ratio (current / prior). Null if prior_count is zero.
    QuestionsAnsweredByOutcome:
      type: object
      required:
      - disposition
      - answered_count
      properties:
        disposition:
          type: integer
          description: 'Case disposition: 0=Pending, 1=NoThreatFound, 5=NonMaliciousPositive, 10=Malicious.'
        label:
          type: string
          description: Human-readable outcome label (Malicious, Benign, Suspicious, etc.).
        answered_count:
          type: integer
          description: Total explore_deeper_questions answered (status != Available, status != Data Needed) across cases with this disposition.
    UpdateInvestigationTiersRequest:
      type: object
      required:
      - organization_id
      - tiers
      properties:
        organization_id:
          type: string
        tiers:
          type: array
          minItems: 1
          items:
            $ref: '#/components/schemas/UpdateInvestigationTierItem'
    ChatSessionDetail:
      type: object
      required:
      - chat_session_id
      - title
      - owner_details
      - created_at
      - deleted
      properties:
        chat_session_id:
          type: string
        title:
          type: string
        owner_details:
          $ref: '#/components/schemas/UserDetail'
        created_at:
          type: integer
          format: int64
        deleted:
          type: boolean
          description: Flag indicating if session has been deleted or not
    UpdateScoringGuidelinesRequest:
      type: object
      required:
      - guidelines_text
      - scoring_criteria
      properties:
        name:
          type: string
        is_organization_default:
          type: boolean
          description: If true, the scoring guidelines will be set as the default scoring guidelines for the organization.
        guidelines_text:
          type: string
        scoring_criteria:
          type: object
          description: map of scoring criteria
          additionalProperties:
            type: number
            format: double
    RecentMaliciousCase:
      type: object
      required:
      - case_id
      - name
      - disposition
      - severity
      - created_at
      properties:
        case_id:
          type: string
        case_uuid:
          type: string
        name:
          type: string
          description: Case name.
        disposition:
          type: integer
          description: Disposition value (2 or 10 = malicious).
        severity:
          type: integer
          description: Severity value.
        created_at:
          type: integer
          format: int64
          description: Case creation time as Unix timestamp (seconds).
        provider:
          type: string
          description: Detection source / provider name.
        provider_display_name:
          type: string
          description: Human-readable provider name.
        category:
          type: string
          description: Threat category.
    SeverityMetrics:
      type: object
      required:
      - alert_count
      properties:
        severity:
          type: integer
        alert_count:
          type: integer
          description: Number of alerts
    CaseAnalyticsEmailRequestFilter:
      type: object
      required:
      - created_at_from
      - created_at_to
      properties:
        org_id:
          type: string
          description: Organization identifier (UUID or org code). If not provided, uses the Organization-ID header value
        created_at_from:
          type: integer
          format: int64
          description: Unix epoch seconds (start of date range)
        created_at_to:
          type: integer
          format: int64
          description: Unix epoch seconds (end of date range)
        metadata:
          type: object
          description: Optional metadata for report customization
    CaseScore:
      type: object
      required:
      - score
      - raw_score
      - summary
      - raw_evaluation
      - referenced_scoring_guidelines
      properties:
        score:
          type: number
          format: double
        raw_score:
          type: number
          format: double
        summary:
          type: string
        raw_evaluation:
          type: array
          items:
            type: object
        referenced_scoring_guidelines:
          $ref: '#/components/schemas/ScoringGuidelines'
          description: list of referenced scoring guidelines
        score_status:
          $ref: '#/components/schemas/ScoreStatus'
          description: status of the score
    ExecutiveDashboardData:
      type: object
      description: Curated executive-view widgets. KPI card + escalation, detection, trend, and threat widgets reused from the analytics/SOC dashboards, plus recent malicious cases and MITRE category volume.
      properties:
        kpi:
          $ref: '#/components/schemas/KpiWidgets'
        escalations_by_disposition:
          type: array
          items:
            $ref: '#/components/schemas/CommunicationByDisposition'
          description: Escalated vs non-escalated case counts grouped by disposition (with_communication = escalated).
        escalations_by_provider:
          type: array
          items:
            $ref: '#/components/schemas/ProviderEscalationCount'
          description: Escalated vs benign case counts grouped by security vendor (detection source).
        high_value_detections:
          type: array
          items:
            $ref: '#/components/schemas/AlertTypeCount'
          description: Alert types most likely to be malicious.
        false_positive_alert_types:
          type: array
          items:
            $ref: '#/components/schemas/AlertTypeCount'
          description: Alert types most likely to be false positives.
        cases_over_time:
          type: array
          items:
            $ref: '#/components/schemas/DailyCount'
          description: Daily total case volume within the requested window.
        escalations_over_time:
          type: array
          items:
            $ref: '#/components/schemas/DailyCount'
          description: Daily escalated case volume within the requested window.
        cases_by_threat_type:
          type: array
          items:
            $ref: '#/components/schemas/CategoryCount'
          description: Case count grouped by threat category.
        escalations_by_severity:
          type: array
          items:
            $ref: '#/components/schemas/SeverityCount'
          description: Escalated case count broken down by severity level.
        recent_malicious_cases:
          type: array
          items:
            $ref: '#/components/schemas/RecentMaliciousCase'
          description: Most recent malicious cases (disposition in [2,10]), newest first.
        mitre_category_volume:
          type: array
          items:
            $ref: '#/components/schemas/EmergingThreat'
          description: Case volume per threat category, current window vs the prior equal window.
    ListCaseScoresRequest:
      type: object
      properties:
        accessible_organization_ids:
          type: array
          items:
            type: string
          description: List of organization IDs for which scores are needed.
        date_range:
          $ref: '#/components/schemas/TimeRange'
          description: Date range for which scores are needed.
    CaseActionsFilter:
      type: object
      properties:
        include_closed_cases:
          type: boolean
          default: false
          description: Whether to include actions from closed cases
        action_severity:
          type: array
          items:
            $ref: '#/components/schemas/ActionSeverityLevel'
          description: Filter by action severity levels
        status:
          type: array
          items:
            type: integer
          description: Filter by action status values; defaults to [New, Pending, Customer Pending, Approved, Rejected]
        status_v2:
          type: array
          items:
            $ref: '#/components/schemas/ActionStatusV2'
          description: Filter by action lifecycle status values (status_v2)
        priority:
          type: array
          items:
            type: string
            enum:
            - Containment
            - Required
            - Recommended
          description: Filter by action priority values
        case_ids:
          type: array
          items:
            type: string
          description: Filter to specific case IDs
        case_modified_at:
          $ref: '#/components/schemas/CaseActionsDateRange'
          description: Filter by case modified_at range (epoch seconds)
        assignee:
          type: string
          enum:
          - my
          - all
          - list
          default: my
          description: Assignee scope — "my" for current user, "all" for everyone, "list" to specify assignee_list
        assignee_list:
          type: array
          items:
            $ref: '#/components/schemas/CaseActionsFilterAssigneeListItem'
          description: List of assignees to match against; only used when assignee = "list"
        organization_ids:
          type: array
          items:
            type: string
          description: Filter to specific organization IDs; intersected with the caller's accessible orgs
        type:
          type: array
          items:
            type: string
            enum:
            - approval
            - customer_action
            - answer_question
          description: Filter by action type
        search:
          type: string
          description: Free-text search term
    DispositionEscalationWidgets:
      type: object
      properties:
        disposition_breakdown:
          type: array
          items:
            $ref: '#/components/schemas/CommunicationByDisposition'
          description: For each disposition, count of cases with and without customer communication (escalated_to=0).
        escalation_breakdown:
          $ref: '#/components/schemas/EscalationBreakdown'
          description: Case counts split by whether they have at least one customer escalation.
        escalations_by_provider:
          type: array
          items:
            $ref: '#/components/schemas/ProviderEscalationCount'
          description: Escalated vs benign (not escalated) case counts grouped by security vendor (detection source / provider).
    CaseAnalyticsDashboardData:
      type: object
      properties:
        kpi:
          $ref: '#/components/schemas/KpiWidgets'
        network:
          $ref: '#/components/schemas/NetworkWidgets'
        users:
          $ref: '#/components/schemas/UserWidgets'
        hosts:
          $ref: '#/components/schemas/HostWidgets'
        detection:
          $ref: '#/components/schemas/DetectionWidgets'
        trends:
          $ref: '#/components/schemas/TrendWidgets'
        threat_categorization:
          $ref: '#/components/schemas/ThreatCategorizationWidgets'
        remediation:
          $ref: '#/components/schemas/RemediationWidgets'
        disposition_escalation:
          $ref: '#/components/schemas/DispositionEscalationWidgets'
    ThreatCategorizationWidgets:
      type: object
      properties:
        cases_by_threat_type:
          type: array
          items:
            $ref: '#/components/schemas/CategoryCount'
          description: Case count grouped by category field.
        high_severity_by_threat_type:
          type: array
          items:
            $ref: '#/components/schemas/CategoryCount'
          description: Case count for severity in [10,15] (High, Critical) grouped by category.
        emerging_threats:
          type: array
          items:
            $ref: '#/components/schemas/EmergingThreat'
          description: Categories with significant growth vs the prior period.
    Error:
      type: object
      required:
      - message
      properties:
        message:
          type: string
          description: user friendly error message
    AttackTypeCount:
      type: object
      required:
      - type
      - count
      properties:
        type:
          type: string
          description: Alert type name.
        count:
          type: integer
          description: Number of cases involving this alert type for the given entity.
    NetworkWidgets:
      type: object
      properties:
        top_attacking_ips:
          type: array
          items:
            $ref: '#/components/schemas/EntityCount'
          description: Top IPs linked to malicious cases (disposition=10), ranked by case count.
        persistent_ips:
          type: array
          items:
            $ref: '#/components/schemas/EntityCountWithDays'
          description: IPs appearing in more than one case, ranked by case count.
        internal_ips:
          type: array
          items:
            $ref: '#/components/schemas/EntityCount'
          description: RFC1918 IPs generating the most cases.
        top_attacking_domains:
          type: array
          items:
            $ref: '#/components/schemas/EntityCount'
          description: Top domains linked to malicious cases (disposition=10), ranked by case count.
        common_iocs:
          type: array
          items:
            $ref: '#/components/schemas/EntityCount'
          description: All entity types seen across multiple cases, ranked by case count.
    SortOrder:
      type: integer
      enum:
      - 0
      - 1
      x-enum-varnames:
      - Asc
      - Desc
    CaseScoreSummary:
      type: object
      required:
      - case_uuid
      - case_id
      - organization_id
      - provider_id
      - alert_id
      - alert_type
      - case_score
      - raw_score
      - case_score_created_at
      - case_created_at
      properties:
        case_uuid:
          type: string
        case_id:
          type: string
        organization_id:
          type: string
        provider_id:
          type: string
        alert_id:
          type: string
        alert_type:
          type: string
        case_score:
          type: number
        raw_score:
          type: number
          format: double
        case_score_created_at:
          type: integer
          format: int64
        case_created_at:
          type: integer
          format: int64
    ActionSeverityLevel:
      type: string
      enum:
      - Critical
      - High
      - Medium
      - Low
      x-enum-varnames:
      - CriticalActionSeverity
      - HighActionSeverity
      - MediumActionSeverity
      - LowActionSeverity
    CaseActionsFilterAssigneeListItem:
      type: object
      required:
      - id
      - type
      properties:
        id:
          type: string
          description: UUID of the user or user group to match
        type:
          type: string
          enum:
          - user
          - group
          description: Whether id should be matched against users or user groups
    ListCaseScoresResponse:
      type: object
      required:
      - message
      - data
      - total
      properties:
        message:
          type: string
        data:
          type: array
          items:
            $ref: '#/components/schemas/CaseScoreSummary'
          description: List of case scores.
        total:
          type: integer
          description: Total number of scores found.
    CostTrimAlertTypeRow:
      allOf:
      - $ref: '#/components/schemas/CostTrimRollupBase'
      - type: object
        required:
        - alert_type
        properties:
          alert_type:
            type: string
    SocEmailResponse:
      type: object
      required:
      - message
      properties:
        message:
          type: string
          description: Status message confirming email was queued
    SeverityCount:
      type: object
      required:
      - severity
      - severity_label
      - count
      properties:
        severity:
          type: integer
          description: Severity value (0=Unassigned, 1=Low, 2=Informational, 5=Medium, 10=High, 15=Critical).
        severity_label:
          type: string
          description: Human-readable severity label.
        count:
          type: integer
          description: Number of cases with this severity.
    GetDetailedMetricsRequest:
      type: object
      properties:
        global_metrics_organization_filter:
          type: array
          items:
            type: string
          description: Organization IDs for which the global metrics should be fetched
        alert_type_metrics_organization_filter:
          type: array
          items:
            type: string
          description: Organization IDs for which the alert type metrics should be fetched
    AlertSource:
      type: integer
      enum:
      - 0
      x-enum-varnames:
      - ManualAlertSource
    EmailCaseDetailsRequest:
      type: object
      required:
      - to_addresses
      properties:
        to_addresses:
          type: array
          items:
            type: string
          description: list of emails to send the case details to
        subject:
          type: string
          description: subject of the email
        html_content:
          type: string
          description: html content for the email body
        message:
          type: string
          description: message to be sent in email body along with html content
        include_hidden_findings:
          type: boolean
          description: if true, hidden findings will be included in the email
        view_id:
          type: string
          description: id of the saved case view whose section layout should drive the emailed case details (v2 only). Resolved against the requestor's organization. When omitted, falls back to the default saved view of the organization the case belongs to.
    GlobalMetrics:
      allOf:
      - $ref: '#/components/schemas/Metrics'
      - type: object
        required:
        - failed_alert_count
        - successful_alert_sources
        - failed_alert_sources
        - successful_sources_without_alerts
        properties:
          global_provider_metrics_list:
            type: array
            items:
              $ref: '#/components/schemas/ProviderMetrics'
            description: Provider metrics list
          failed_alert_count:
            type: integer
            description: Number of failed alerts
          successful_alert_sources:
            type: array
            items:
              type: string
            description: List of successful alert sources
          failed_alert_sources:
            type: array
            items:
              type: string
            description: List of failed alert sources
          successful_sources_without_alerts:
            type: array
            items:
              type: string
            description: List of successful sources without alerts
    DetailedMetrics:
      type: object
      required:
      - provider_metrics_list
      - global_metrics
      properties:
        provider_metrics_list:
          type: array
          items:
            $ref: '#/components/schemas/ProviderMetrics'
          description: Provider metrics list
        alert_type_metrics_list:
          type: array
          items:
            $ref: '#/components/schemas/AlertTypeMetrics'
          description: Alert type metrics list
        global_metrics:
          $ref: '#/components/schemas/GlobalMetrics'
          description: Global metrics
        daily_metrics_list:
          type: array
          items:
            $ref: '#/components/schemas/DailyMetrics'
          description: Daily metrics list
    CaseSeverity:
      type: integer
      enum:
      - 0
      - 1
      - 5
      - 10
      - 20
      x-enum-varnames:
      - InformationalCaseSeverity
      - LowCaseSeverity
      - MediumCaseSeverity
      - HighCaseSeverity
      - CriticalCaseSeverity
    CaseActionsDateRange:
      type: object
      properties:
        start:
          type: integer
          format: int64
          description: Start of range (unix epoch seconds, inclusive)
        end:
          type: integer
          format: int64
          description: End of range (unix epoch seconds, inclusive)
    KpiWidgets:
      type: object
      required:
      - total_cases
      - cases_escalated
      - pending_case_actions
      properties:
        total_cases:
          type: integer
          description: Distinct cases created within the selected window.
        cases_escalated:
          type: integer
          description: Cases with at least one escalation (escalation_type=Escalated).
        pending_case_actions:
          type: integer
          description: Count of open case action items — matches the listCaseActionsV1 total (non-closed cases, non-empty actions, scoped to the window on modified_at).
        mtti_seconds:
          type: number
          format: float
          description: Mean time to investigate (investigation_completed_at - alert_acknowledged_at) in seconds, excluding cases flagged ignore_case_metric. Absent when no qualifying cases.
    QualityScoreDailyPoint:
      type: object
      required:
      - date
      properties:
        date:
          type: string
          description: Date in YYYY-MM-DD format.
        overall:
          type: number
          format: double
          description: Average case_score across all cases on this day.
        darryl_investigated:
          type: number
          format: double
          description: Average case_score for Darryl-investigated cases on this day.
        human_investigated:
          type: number
          format: double
          description: Average case_score for human-investigated cases on this day.
    AppendMode:
      type: integer
      enum:
      - 0
      - 1
      x-enum-varnames:
      - NewLine
      - Space
    CostTrimAnalysisResponse:
      type: object
      required:
      - view
      - stale
      - rows
      - totals
      properties:
        computed_at:
          type: integer
          format: int64
          description: Unix timestamp (seconds) when the newest matching snapshot row was computed.
        window_start:
          type: integer
          format: int64
          description: Unix timestamp (seconds) for the start of the snapshot window.
        window_end:
          type: integer
          format: int64
          description: Unix timestamp (seconds) for the end of the snapshot window.
        view:
          type: string
          description: The roll-up shape applied to `rows`.
        stale:
          type: boolean
          description: True when the newest snapshot is older than the configured freshness window.
        rows:
          description: 'Roll-up rows. Shape depends on the `view` query param — see the

            view-specific row schemas (`CostTrimSnapshotRow`,

            `CostTrimOrgRow`, etc.) for the possible shapes.

            '
          oneOf:
          - type: array
            items:
              $ref: '#/components/schemas/CostTrimSnapshotRow'
          - type: array
            items:
              $ref: '#/components/schemas/CostTrimOrgRow'
          - type: array
            items:
              $ref: '#/components/schemas/CostTrimOrgTypeRow'
          - type: array
            items:
              $ref: '#/components/schemas/CostTrimProviderTypeRow'
          - type: array
            items:
              $ref: '#/components/schemas/CostTrimProviderRow'
          - type: array
            items:
              $ref: '#/components/schemas/CostTrimAlertTypeRow'
          - type: array
            items:
              $ref: '#/components/schemas/CostTrimEscalationsByTypeRow'
        totals:
          $ref: '#/components/schemas/CostTrimTotals'
    CaseMetricsLLMSummary:
      type: object
      required:
      - risk
      - tag
      - title
      - details
      - footer_label
      - footer_text
      properties:
        risk:
          type: string
          description: Drives the chip color. Accepts color-semantic (info/success/warning/danger, emitted by /query_metrics) or severity (Critical/High/Medium/Low/Informational, emitted by the monthly report).
          enum:
          - info
          - success
          - warning
          - danger
          - Critical
          - High
          - Medium
          - Low
          - Informational
          x-enum-varnames:
          - InfoLLMSummaryRisk
          - SuccessLLMSummaryRisk
          - WarningLLMSummaryRisk
          - DangerLLMSummaryRisk
          - CriticalLLMSummaryRisk
          - HighLLMSummaryRisk
          - MediumLLMSummaryRisk
          - LowLLMSummaryRisk
          - InformationalLLMSummaryRisk
        tag:
          type: string
          description: Chip label, e.g. "1 CRITICAL ESCALATION", "TELEMETRY GAP".
        title:
          type: string
          description: a brief summary text of this briefing point in < 10 words
        details:
          type: string
          description: Narrative paragraph describing the briefing point.
        footer_label:
          type: string
          description: Footer flips between a resolved/no-action STATUS line and a NEXT STEP line.
          enum:
          - STATUS
          - NEXT STEP
          x-enum-varnames:
          - StatusLLMSummaryFooter
          - NextStepLLMSummaryFooter
        footer_text:
          type: string
          description: Footer body text for the STATUS / NEXT STEP line.
    MultiVectorUser:
      type: object
      required:
      - name
      - attack_types
      properties:
        name:
          type: string
          description: Username or service account name.
        attack_types:
          type: array
          items:
            $ref: '#/components/schemas/AttackTypeCount'
          description: Distinct alert types this user has been involved in, with case count per type.
        case_count:
          type: integer
    CommunicationByDisposition:
      type: object
      required:
      - disposition
      - with_communication
      - without_communication
      properties:
        disposition:
          type: integer
        disposition_label:
          type: string
        with_communication:
          type: integer
        without_communication:
          type: integer
    CaseListRequest:
      type: object
      required:
      - requested_view
      properties:
        minimal:
          type: boolean
          description: Indicates if data is for minimum details or not
        requested_view:
          $ref: '#/components/schemas/CaseView'
          description: Indicates which view is requested
        filter:
          $ref: '#/components/schemas/CaseFilter'
        sort:
          type: array
          items:
            $ref: '#/components/schemas/CaseSort'
          description: list of sort fields in order
    MttiComparisonPoint:
      type: object
      required:
      - x
      - y
      properties:
        x:
          type: number
          format: float
          description: Average investigation time in minutes.
        y:
          type: number
          format: float
          description: Time difference (avg_mtti - x) in minutes.
    CategoryCount:
      type: object
      required:
      - category
      - count
      properties:
        category:
          type: string
        count:
          type: integer
    CaseActionsResponse:
      type: object
      required:
      - message
      - items
      - total
      properties:
        message:
          type: string
        items:
          type: array
          items:
            $ref: '#/components/schemas/CaseActionListItem'
          description: Paginated list of case actions
        total:
          type: integer
          description: Total count of matching actions (for pagination)
    AnalystPerformance:
      type: object
      required:
      - assignee_email
      - case_count
      properties:
        assignee_email:
          type: string
        case_count:
          type: integer
          description: Number of cases assigned to this analyst in the window.
        avg_mtti_seconds:
          type: integer
          description: Average MTTI in seconds for this analyst's cases (manual cases only).
    GenerateCaseScoreRequest:
      type: object
      properties:
        new_scoring_guidelines:
          $ref: '#/components/schemas/ScoringGuidelines'
    AggregatedMetrics:
      allOf:
      - $ref: '#/components/schemas/DetailedMetrics'
      - type: object
        required:
        - organization_metrics_list
        properties:
          organization_metrics_list:
            type: array
            items:
              $ref: '#/components/schemas/OrganizationMetrics'
              description: Organization metrics list
    ProviderEscalationCount:
      type: object
      required:
      - provider
      - escalated_count
      - not_escalated_count
      - total
      properties:
        provider:
          type: string
          description: Detection source / provider name (security vendor). "Unknown" when the case has no provider.
        display_name:
          type: string
          description: Human-readable provider name.
        escalated_count:
          type: integer
          description: Cases from this provider with at least one escalation.
        not_escalated_count:
          type: integer
          description: Benign cases from this provider (no escalation).
        total:
          type: integer
          description: Total cases from this provider.
    BusinessHoursBreakdown:
      type: object
      required:
      - business_hours_count
      - after_hours_count
      - total
      properties:
        business_hours_count:
          type: integer
          description: Cases created during standard business hours (Mon–Fri 09:00–17:00 UTC).
        after_hours_count:
          type: integer
          description: Cases created outside business hours — nights, early mornings, and weekends (UTC).
        total:
          type: integer
          description: Total cases across both buckets.
        ai_summary:
          type: string
          description: AI-generated natural-language summary of the business-hours breakdown. Populated separately; may be absent.
    CostTrimRollupBase:
      type: object
      required:
      - alerts
      - investigated
      - escalations
      - efficacy
      properties:
        alerts:
          type: integer
          format: int64
        investigated:
          type: integer
          format: int64
        linked_case_count:
          type: integer
          format: int64
        escalations:
          type: integer
          format: int64
          description: Count of alerts whose linked case was escalated to the customer.
        escalated_to_analyst:
          type: integer
          format: int64
        efficacy:
          type: number
          format: double
    ThroughputWidgets:
      type: object
      properties:
        total_cases:
          type: integer
          description: Total cases created in the date window.
        daily_case_volume:
          type: array
          items:
            $ref: '#/components/schemas/DailyCount'
          description: Case count per day in the window.
        analyst_performance:
          type: array
          items:
            $ref: '#/components/schemas/AnalystPerformance'
          description: Per-analyst case volume and avg MTTI (manual cases only).
        peak_load_by_hour:
          type: array
          items:
            $ref: '#/components/schemas/HourCount'
          description: Case volume by hour of day (UTC) — peak load signal.
        adr_triage_breakdown:
          type: array
          items:
            $ref: '#/components/schemas/AdrTriageCount'
          description: Distribution of cases by automation tier (adr_triage).
        status_breakdown:
          type: object
          additionalProperties:
            type: integer
          description: Case count grouped by status (status_id → count).
    GenerateBulkCaseScoresRequest:
      type: object
      required:
      - case_uuids
      properties:
        case_uuids:
          type: array
          items:
            type: string
          description: List of case UUIDs for which scores are needed.
    ActionExecutionDetails:
      type: object
      properties:
        execution_id:
          type: string
          description: ID of the execution triggered against knowledge-management for this action
        execution_status:
          type: string
          description: Last known execution status, as reported by knowledge-management's GetExecutionLogAPI
        started_by:
          type: string
          description: ID of the user who started the execution
        started_at:
          type: integer
          format: int64
          description: Timestamp the execution was started; used to bound how long the execution is polled before it is force-resolved as failed
    UserDetails:
      type: object
      properties:
        firstname:
          type: string
        lastname:
          type: string
        user_uuid:
          type: string
        performed_by_darryl:
          type: boolean
    CaseType:
      type: integer
      enum:
      - 0
      - 5
      x-enum-varnames:
      - BasicCaseType
      - V2CaseType
    ReworkDailyPoint:
      type: object
      required:
      - date
      - rework_count
      - rework_rate
      properties:
        date:
          type: string
          description: Date in YYYY-MM-DD format.
        rework_count:
          type: integer
          description: Number of reinvestigated cases on this day.
        rework_rate:
          type: number
          format: float
          description: rework_count / total_cases_that_day as a percentage.
        avg_rework_seconds:
          type: integer
          description: Average time from case_closed_at to reinvestigated_at for reinvestigated cases on this day.
    Metrics:
      allOf:
      - $ref: '#/components/schemas/CaseReviewMetrics'
      - type: object
        properties:
          darryl_reviewed_case_metrics:
            $ref: '#/components/schemas/CaseReviewMetrics'
            description: Darryl reviewed case metrics
          human_reviewed_case_metrics:
            $ref: '#/components/schemas/CaseReviewMetrics'
            description: Human reviewed case metrics
          darryl_investigated_cases:
            type: integer
            description: Number of cases investigated by darryl
          human_investigated_cases:
            type: integer
            description: Number of cases investigated by human
          alert_count:
            type: integer
            description: Number of alerts
          alert_type_count:
            type: integer
            description: Number of alert types
    Success:
      type: object
      required:
      - message
      properties:
        message:
          type: string
          description: user friendly message
    ConsistencyWidgets:
      type: object
      properties:
        outlier_cases:
          type: array
          items:
            $ref: '#/components/schemas/OutlierCase'
          description: Top slowest investigations by investigation_completed_metric, descending.
    SocEmailRequest:
      type: object
      required:
      - email_ids
      - subject
      - filter
      properties:
        email_ids:
          type: array
          items:
            type: string
          description: List of email addresses to send the report to
        subject:
          type: string
          description: Email subject line. If empty, a default subject will be generated.
        filter:
          $ref: '#/components/schemas/SocEmailRequestFilter'
          description: Filter parameters for the report
    HourCount:
      type: object
      required:
      - hour
      - count
      properties:
        hour:
          type: integer
          description: Hour of day in UTC (0–23).
        count:
          type: integer
          description: Number of cases created in this hour across all days in the window.
    OperationalGapsWidgets:
      type: object
      properties:
        missing_telemetry_by_alert_type:
          type: array
          items:
            $ref: '#/components/schemas/MissingTelemetryCount'
          description: Cases with non-empty confidence.missing_information, grouped by alert_type.
        blocked_by_customer_by_category:
          type: array
          items:
            $ref: '#/components/schemas/BlockedByCategoryCount'
          description: Cases with status=10 OR actions_required[status=2], grouped by category and severity tier.
    ExecutiveDashboardResponse:
      type: object
      required:
      - message
      - data
      properties:
        message:
          type: string
        data:
          $ref: '#/components/schemas/ExecutiveDashboardData'
    BulkDeleteCasesResponse:
      type: object
      required:
      - message
      - data
      properties:
        message:
          type: string
        data:
          type: array
          items:
            type: string
          description: UUIDs of the case deleted
    ResponseTimeMetric:
      type: object
      required:
      - avg_seconds
      - case_count
      - mean_metrics_intervals
      - daily_mean_metrics
      properties:
        avg_seconds:
          type: integer
        case_count:
          type: integer
        mean_metrics_intervals:
          type: object
          additionalProperties:
            type: number
            format: float
        daily_mean_metrics:
          type: object
          additionalProperties:
            type: number
            format: float
    QuestionsAnsweredSplit:
      type: object
      required:
      - answered
      - unanswered
      - total
      properties:
        answered:
          type: integer
          description: Questions where status is not Available or Data Needed.
        unanswered:
          type: integer
          description: Questions where status is Available or Data Needed.
        total:
          type: integer
    UpdateInvestigationTierItem:
      type: object
      required:
      - alert_provider
      - alert_type
      - investigation_tier
      properties:
        alert_provider:
          type: string
        alert_type:
          type: string
        investigation_tier:
          type: string
          enum:
          - L1
          - L2
          - L3
    BlockedByCategoryCount:
      type: object
      required:
      - category
      - total
      properties:
        category:
          type: string
        critical_high_count:
          type: integer
          description: Blocked cases with severity in [10, 15] (High, Critical).
        medium_count:
          type: integer
          description: Blocked cases with severity=5 (Medium).
        low_info_count:
          type: integer
          description: Blocked cases with severity in [0, 1, 2] (Unassigned, Low, Informational).
        total:
          type: integer
          description: Total blocked cases in this category.
    Case:
      type: object
      required:
      - case_id
      - case_uuid
      - name
      - status
      - severity
      - priority
      - assignee
      - reporter
      - created_at
      - modified_at
      properties:
        case_id:
          type: string
          description: Unique number respresenting case of an organization
        case_uuid:
          type: string
          description: Unique identifier of case
        name:
          type: string
          description: Title of the case
        status:
          $ref: '#/components/schemas/CaseStatus'
        severity:
          $ref: '#/components/schemas/CaseSeverity'
        priority:
          $ref: '#/components/schemas/CasePriority'
        assignee:
          $ref: '#/components/schemas/UserDetails'
        reporter:
          $ref: '#/components/schemas/UserDetails'
        archived:
          type: boolean
          description: Flag indicating if the case has been archived or not
        escalated_to_customer:
          type: boolean
        created_at:
          type: integer
          format: int64
          description: Timestamp of creation of the case.
        modified_at:
          type: integer
          format: int64
          description: Timestamp of the last modification of the case.
    GenerateBulkCaseScoresResponse:
      type: object
      required:
      - message
      - data
      properties:
        message:
          type: string
        data:
          type: array
          items:
            $ref: '#/components/schemas/CaseScore'
    AutomationWidgets:
      type: object
      properties:
        time_saved_chart:
          type: array
          items:
            $ref: '#/components/schemas/MttiComparisonPoint'
          description: Line chart data showing time difference (avg_mtti - x) for investigation durations from min to max in 1-minute increments.
        adr_triage_trend:
          type: array
          items:
            $ref: '#/components/schemas/AdrTriageDailyBreakdown'
          description: Daily automation tier breakdown for trend chart.
    ArchiveCasesResponse:
      type: object
      required:
      - message
      - data
      properties:
        message:
          type: string
        data:
          type: array
          items:
            type: string
          description: UUIDs of the case archived
    ProviderList:
      type: object
      required:
      - provider
      - alert_count
      properties:
        provider:
          $ref: '#/components/schemas/ProviderSummary'
        alert_count:
          type: integer
          description: Number of alerts
    AssigneeDetails:
      type: object
      required:
      - assignee_id
      - assignee_type
      properties:
        firstname:
          type: string
        lastname:
          type: string
        email:
          type: string
        assignee_id:
          type: string
        user_uuid:
          type: string
        assignee_type:
          type: string
        performed_by_darryl:
          type: boolean
    InvestigationCreditsResponse:
      type: object
      required:
      - limit_set
      properties:
        limit_set:
          type: boolean
          description: false when the organization has no credit allocation (unlimited)
        week_start:
          type: string
          description: Monday of the current week (UTC), "YYYY-MM-DD"
        weekly_allocation:
          type: number
          format: double
        rolled_over:
          type: number
          format: double
        credits_available:
          type: number
          format: double
        credits_used:
          type: number
          format: double
    EmailCaseDetailsResponse:
      type: object
      required:
      - message
      - failed_deliveries
      properties:
        message:
          type: string
        failed_deliveries:
          type: array
          items:
            type: string
          description: list of emails the case details could not be sent to
    GetCaseResponse:
      type: object
      required:
      - message
      - data
      properties:
        message:
          type: string
        data:
          $ref: '#/components/schemas/CaseDetails'
          description: updated case object
    PercentileMetric:
      type: object
      properties:
        p50_seconds:
          type: integer
          description: 50th percentile (median) value in seconds.
        p95_seconds:
          type: integer
          description: 95th percentile value in seconds.
        p99_seconds:
          type: integer
          description: 99th percentile value in seconds.
    AdrTriageCount:
      type: object
      required:
      - adr_triage
      - count
      properties:
        adr_triage:
          type: integer
          description: 'Automation level: 0=NA, 1=None (manual), 5=Partial, 10=Full (automated).'
        count:
          type: integer
        percentage:
          type: number
          format: float
          description: Percentage of total cases in this tier.
  parameters:
    user-id:
      name: User-ID
      in: header
      description: The User ID of the requestor. If requests are made through API Gateway, this header will be pre filled.
      schema:
        type: string
    x-request-id:
      name: X-Request-ID
      in: header
      description: The ID associated with the request. If requests are made through API Gateway, this header will be pre filled.
      schema:
        type: string
    organization-id:
      name: Organization-ID
      in: header
      description: The Organization ID of the requestor. If requests are made through API Gateway, this header will be pre filled.
      schema:
        type: string
  securitySchemes:
    SessionCookie:
      type: apiKey
      in: cookie
      name: Session
x-tagGroups:
- name: Included APIs
  tags:
  - Case Manager V2
  - Dashboard
  - Alerts
  - Webhooks
  - Query DSL