openapi: 3.2.0
info:
  title: Case Manager Query DSL API
  version: 1.0.0
servers:
- url: /airmdrapi
tags:
- name: Query DSL
paths:
  /v2/query/execute:
    post:
      tags:
      - Query DSL
      operationId: executeQueryAPI
      summary: Execute a DSL query against cases or alerts
      description: 'Executes a custom query using the Query DSL. Results are automatically filtered

        by the user''s accessible organizations. Supports filtering, sorting, pagination,

        and aggregations for dashboard analytics.'
      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/QueryExecuteRequest'
            examples:
              list_open_cases:
                summary: List open critical cases
                value:
                  collection: cases
                  select:
                  - case_id
                  - name
                  - status
                  - severity
                  - created_at
                  - assignee_name
                  where:
                    status: 0
                    severity:
                      $in:
                      - 0
                      - 1
                  sort:
                    created_at: desc
                  limit: 50
              count_by_status:
                summary: Count cases by status
                value:
                  collection: cases
                  aggregate:
                    group_by:
                    - status
                    metrics:
                      count:
                        $count: true
                  where:
                    created_at:
                      $gte: -30d
              unresolved_alerts:
                summary: Find unresolved alerts by provider
                value:
                  collection: alerts
                  select:
                  - alert_id
                  - alert_type
                  - alert_provider
                  - created_at
                  where:
                    resolved: false
                    alert_provider: crowdstrike
                  sort:
                    created_at: desc
              date_aggregation:
                summary: Cases created per day
                value:
                  collection: cases
                  aggregate:
                    group_by:
                    - date:
                        $dateGroup: created_at
                        unit: day
                    metrics:
                      count:
                        $count: true
                  where:
                    created_at:
                      $gte: -30d
      security:
      - SessionCookie: []
      responses:
        '200':
          description: Query executed successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QueryExecuteResponse'
              examples:
                list_results:
                  summary: List query results
                  value:
                    data:
                    - case_id: CASE-001
                      name: Phishing attempt detected
                      status: 0
                      severity: 1
                      created_at: 1706745600
                      assignee_name: John Doe
                    - case_id: CASE-002
                      name: Suspicious login activity
                      status: 0
                      severity: 0
                      created_at: 1706659200
                      assignee_name: Jane Smith
                    total: 125
                    limit: 50
                    offset: 0
                    collection: cases
                aggregation_results:
                  summary: Aggregation results
                  value:
                    data:
                    - status: 0
                      count: 45
                    - status: 1
                      count: 30
                    - status: 2
                      count: 50
                    total: 3
                    limit: 100
                    offset: 0
                    collection: cases
        '400':
          description: Invalid query
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QueryErrorResponse'
              example:
                message: validation failed
                errors:
                - field: where
                  message: unknown field 'invalid_field' in where clause
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /v2/query/validate:
    post:
      tags:
      - Query DSL
      operationId: validateQueryAPI
      summary: Validate a DSL query without executing it
      description: 'Validates a query against the schema without executing it.

        Useful for checking query syntax before execution.'
      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/QueryValidateRequest'
      security:
      - SessionCookie: []
      responses:
        '200':
          description: Validation result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QueryValidateResponse'
              examples:
                valid:
                  summary: Valid query
                  value:
                    valid: true
                    errors: []
                invalid:
                  summary: Invalid query
                  value:
                    valid: false
                    errors:
                    - field: where
                      message: unknown field 'invalid_field' in where clause
                    - field: sort
                      message: field 'non_sortable' is not sortable
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /v2/query/schema:
    get:
      tags:
      - Query DSL
      operationId: getQuerySchemaAPI
      summary: Get available query schemas
      description: 'Returns the schema for all queryable collections, including available fields

        and their capabilities (filterable, selectable, sortable, aggregatable).'
      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
      security:
      - SessionCookie: []
      responses:
        '200':
          description: Schema retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QuerySchemaResponse'
              example:
                collections:
                  cases:
                    name: cases
                    fields:
                      case_id:
                        type: string
                        filterable: true
                        selectable: true
                        sortable: true
                        aggregatable: false
                      status:
                        type: int
                        filterable: true
                        selectable: true
                        sortable: true
                        aggregatable: true
                      severity:
                        type: int
                        filterable: true
                        selectable: true
                        sortable: true
                        aggregatable: true
                      created_at:
                        type: datetime
                        filterable: true
                        selectable: true
                        sortable: true
                        aggregatable: true
                  alerts:
                    name: alerts
                    fields:
                      alert_id:
                        type: string
                        filterable: true
                        selectable: true
                        sortable: true
                        aggregatable: false
                      alert_type:
                        type: string
                        filterable: true
                        selectable: true
                        sortable: false
                        aggregatable: true
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    QuerySchemaResponse:
      type: object
      required:
      - collections
      properties:
        collections:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/CollectionSchema'
          description: Available collection schemas
    QueryExecuteResponse:
      type: object
      required:
      - data
      - total
      - limit
      - offset
      - collection
      properties:
        data:
          type: array
          items:
            type: object
            additionalProperties: true
          description: Query results
        total:
          type: integer
          description: Total number of matching documents
        limit:
          type: integer
          description: Limit used for the query
        offset:
          type: integer
          description: Offset used for the query
        collection:
          type: string
          description: Collection that was queried
    QueryExecuteRequest:
      type: object
      required:
      - collection
      properties:
        collection:
          type: string
          description: The collection to query (cases or alerts)
          enum:
          - cases
          - alerts
        select:
          type: array
          items:
            type: string
          description: Fields to return in the response. If empty, returns all selectable fields.
        where:
          type: object
          additionalProperties: true
          description: Filter conditions. Keys are field names, values are either direct values or operator objects.
        sort:
          type: object
          additionalProperties:
            type: string
            enum:
            - asc
            - desc
          description: Sort fields and directions
        limit:
          type: integer
          minimum: 1
          maximum: 10000
          default: 100
          description: Maximum number of results to return
        offset:
          type: integer
          minimum: 0
          default: 0
          description: Number of results to skip
        aggregate:
          $ref: '#/components/schemas/AggregateRequest'
          description: Aggregation configuration for analytics queries
    QueryValidationError:
      type: object
      required:
      - field
      - message
      properties:
        field:
          type: string
          description: Field that caused the error
        message:
          type: string
          description: Error description
    QueryValidateResponse:
      type: object
      required:
      - valid
      properties:
        valid:
          type: boolean
          description: Whether the query is valid
        errors:
          type: array
          items:
            $ref: '#/components/schemas/QueryValidationError'
          description: Validation errors if any
    QueryErrorResponse:
      type: object
      required:
      - message
      properties:
        message:
          type: string
          description: Error message
        errors:
          type: array
          items:
            $ref: '#/components/schemas/QueryValidationError'
          description: Detailed validation errors
    FieldSchema:
      type: object
      required:
      - type
      - filterable
      - selectable
      - sortable
      - aggregatable
      properties:
        type:
          type: string
          enum:
          - string
          - int
          - bool
          - datetime
          - array
          description: Field data type
        filterable:
          type: boolean
          description: Whether this field can be used in where clauses
        selectable:
          type: boolean
          description: Whether this field can be included in select
        sortable:
          type: boolean
          description: Whether this field can be used for sorting
        aggregatable:
          type: boolean
          description: Whether this field can be used in group_by
    CollectionSchema:
      type: object
      required:
      - name
      - fields
      properties:
        name:
          type: string
          description: Collection name
        fields:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/FieldSchema'
          description: Available fields in this collection
        array_fields:
          type: object
          additionalProperties:
            type: string
          description: 'Valid unwind names and their MongoDB paths.

            Keys are the values accepted in aggregate.unwind (e.g. "entities", "events").

            Use these to discover which array fields support unwind-based aggregation.

            '
    Error:
      type: object
      required:
      - message
      properties:
        message:
          type: string
          description: user friendly error message
    AggregateRequest:
      type: object
      properties:
        group_by:
          type: array
          items:
            oneOf:
            - type: string
              description: Field name to group by
            - type: object
              description: Complex grouping like date truncation {"$dateTrunc":{"field":"created_at","unit":"day"}}
              additionalProperties: true
          description: Fields to group by
        metrics:
          type: object
          additionalProperties:
            type: object
            additionalProperties: true
          description: Metric definitions with aggregation operators
        unwind:
          type: string
          description: 'Array field to unwind before grouping. Required for entity/event-level analytics.

            Valid values per collection — cases: "entities", "events"; alerts: "mitre_tactics".

            Example: unwind "entities" with group_by ["entities.name"] to count cases per IP/user/host.

            '
    QueryValidateRequest:
      type: object
      required:
      - collection
      properties:
        collection:
          type: string
          description: The collection to validate against
          enum:
          - cases
          - alerts
        select:
          type: array
          items:
            type: string
        where:
          type: object
          additionalProperties: true
        sort:
          type: object
          additionalProperties:
            type: string
        limit:
          type: integer
        offset:
          type: integer
        aggregate:
          $ref: '#/components/schemas/AggregateRequest'
  securitySchemes:
    SessionCookie:
      type: apiKey
      in: cookie
      name: Session
x-tagGroups:
- name: Included APIs
  tags:
  - Case Manager V2
  - Dashboard
  - Alerts
  - Webhooks
  - Query DSL