Armor JSM - Incidents API

openapi: 3.2.0
info:
  title: MDR Public JSM - Incidents API
  version: 1.0.0
  description: 'Comprehensive API documentation for Armor''s Managed Detection and Response (MDR) platform.


    This unified API provides access to:


    ## AI Platform (AIP)

    - AI-processed incident analysis with threat indicators and recommendations

    - Entity threat intelligence for security entities associated with incidents


    ## Microsoft Defender Integration

    - Machine/device management in Microsoft Defender for Endpoint

    - Security action execution (isolation, scans, investigations)

    - Investigation package collection and live response operations


    ## Detection Rules Management

    - Microsoft Sentinel detection rules across customer environments

    - Enriched rule metadata including MITRE ATT&CK mappings

    - Incident generation statistics


    ## JSM Middleware

    - Security incident management and tracking

    - Metrics aggregation and reporting

    - Service request management

    - Organization management


    ## Monthly Security Reports

    - Access to monthly security reports (PowerPoint, JSON, PDF)

    - Security metrics and performance indicators

    - Data ingestion analytics


    ## Threat Intelligence

    - Threat actor intelligence data

    - Customer-specific threat intelligence based on deployed products

    - OpenCTI GraphQL proxy for advanced queries


    ## Authentication

    All endpoints (except health checks) require OAuth2 Bearer token authentication.


    For authentication details, see: https://kb.armor.com/kb/sso-authentication-with-postman

    '
  contact:
    name: Armor Security Team
    url: https://armor.com
servers:
- url: https://mdr.api.secure-prod.services
  description: Production environment
- url: https://mdr.api.secure-dev.services
  description: Development environment
security:
- OAuth2BearerAuth: []
- FH-AUTH: []
tags:
- name: JSM - Incidents
  description: Security incident management
paths:
  /incidents:
    get:
      tags:
      - JSM - Incidents
      summary: List incidents
      description: 'Retrieve a paginated list of security incidents from JSM with filtering and sorting options.

        '
      operationId: listIncidents
      parameters:
      - name: sortBy
        in: query
        description: Field to sort by
        schema:
          type: string
          enum:
          - id
          - status
          - summary
          - priority
          - severity
          - updated
          - created
          default: id
      - name: sortDirection
        in: query
        description: Sort direction
        schema:
          type: string
          enum:
          - asc
          - desc
          default: desc
      - name: textSearch
        in: query
        description: Text search query
        schema:
          type: string
      - name: startAt
        in: query
        description: Pagination start index
        schema:
          type: integer
          minimum: 0
          default: 0
      - name: pageSize
        in: query
        description: Number of items per page
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 20
      - name: priority
        in: query
        description: Comma-separated list of priorities
        schema:
          type: string
      - name: status
        in: query
        description: Comma-separated list of statuses
        schema:
          type: string
      - name: tactic
        in: query
        description: Comma-separated list of MITRE ATT&CK tactics
        schema:
          type: string
      - name: organization
        in: query
        description: Comma-separated list of organization IDs
        schema:
          type: string
      responses:
        '200':
          description: Successfully retrieved incidents
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IncidentListResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '402':
          description: No organizations found
          content:
            text/plain:
              schema:
                type: string
  /incidents/{issueKey}:
    get:
      tags:
      - JSM - Incidents
      summary: Get incident details
      description: 'Retrieve detailed information about a specific security incident including metadata,

        alerts, evidence, impacted assets, comments, and AI-powered insights.

        '
      operationId: getIncidentDetails
      parameters:
      - name: issueKey
        in: path
        required: true
        description: JSM issue key (e.g., SEC-1234)
        schema:
          type: string
          pattern: ^[A-Z]+-[0-9]+$
      responses:
        '200':
          description: Successfully retrieved incident details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IncidentDetails'
        '400':
          description: Bad request
          content:
            text/plain:
              schema:
                type: string
        '401':
          description: Unauthorized
          content:
            text/plain:
              schema:
                type: string
  /incidents/{issueKey}/comments:
    post:
      tags:
      - JSM - Incidents
      summary: Add comment to incident
      description: Add a comment to an incident with optional file attachments
      operationId: addIncidentComment
      parameters:
      - name: issueKey
        in: path
        required: true
        description: JSM issue key
        schema:
          type: string
          pattern: ^[A-Z]+-[0-9]+$
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required:
              - comment
              properties:
                comment:
                  type: string
                  minLength: 1
                  maxLength: 5000
                files:
                  type: array
                  maxItems: 10
                  items:
                    type: string
                    format: binary
      responses:
        '200':
          description: Comment added successfully
          content:
            text/plain:
              schema:
                type: string
        '400':
          description: Bad request
          content:
            text/plain:
              schema:
                type: string
        '401':
          description: Unauthorized
          content:
            text/plain:
              schema:
                type: string
  /incidents/{issueKey}/comment/{commentId}:
    get:
      tags:
      - JSM - Incidents
      summary: Get comment attachments
      description: Retrieve all attachments for a specific comment
      operationId: getCommentAttachments
      parameters:
      - name: issueKey
        in: path
        required: true
        description: JSM issue key
        schema:
          type: string
          pattern: ^[A-Z]+-[0-9]+$
      - name: commentId
        in: path
        required: true
        description: Comment ID
        schema:
          type: string
      responses:
        '200':
          description: Successfully retrieved attachments
          content:
            multipart/mixed:
              schema:
                type: string
                format: binary
        '400':
          description: Error retrieving attachments
          content:
            text/plain:
              schema:
                type: string
components:
  schemas:
    IncidentDetails:
      type: object
      properties:
        tenantId:
          type:
          - string
          - 'null'
        incidentId:
          type:
          - string
          - 'null'
        displayName:
          type:
          - string
          - 'null'
        status:
          type: string
        createdDateTime:
          type:
          - string
          - 'null'
          format: date-time
        lastUpdateDateTime:
          type:
          - string
          - 'null'
          format: date-time
        timeToFirstResponse:
          type:
          - integer
          - 'null'
        timeToResolution:
          type:
          - integer
          - 'null'
        severity:
          type:
          - string
          - 'null'
        mitreTactics:
          type: array
          items:
            type: string
        source:
          type: array
          items:
            type: string
        detectionSource:
          type: string
        assignee:
          type:
          - string
          - 'null'
        ticketUpdatedDateTime:
          type: string
          format: date-time
        ticketCreatedDateTime:
          type: string
          format: date-time
        ticketDescription:
          type: string
        ticketSummary:
          type: string
        incidentLink:
          type: string
        orgs:
          type:
          - array
          - 'null'
          items:
            type: object
            properties:
              id:
                type: string
              name:
                type: string
        comments:
          type: array
          items:
            $ref: '#/components/schemas/Comment'
        alerts:
          type: array
          items:
            type: object
        impactedAssets:
          type: array
          items:
            type: object
        aipStatus:
          type:
          - string
          - 'null'
        aipSummary:
          type: string
        aipShortSummary:
          type: string
        aipEnrichmentUpdateTime:
          type: string
        aipConfidenceScore:
          type:
          - number
          - 'null'
        aipClassification:
          type:
          - string
          - 'null'
        similarIncidents:
          type: array
          items:
            type: object
        threatScore:
          type: integer
        aipDescription:
          type: string
        aipInvestigation:
          type: string
        aipContainmentAndRecovery:
          type: string
        changeLog:
          type: array
          items:
            type: object
    IncidentListItem:
      type: object
      properties:
        id:
          type: string
        summary:
          type: string
        status:
          type: string
        priority:
          type: string
        created:
          type: string
          format: date-time
        updated:
          type: string
          format: date-time
        assignee:
          type:
          - string
          - 'null'
        orgs:
          type:
          - array
          - 'null'
          items:
            type: object
            properties:
              orgId:
                type: string
              orgName:
                type: string
        tactics:
          type: array
          items:
            type: object
            properties:
              name:
                type: string
              id:
                type: string
    Comment:
      type: object
      properties:
        id:
          type: string
        authorDisplayName:
          type: string
        authorEmail:
          type: string
        body:
          type: string
        created:
          type: string
          format: date-time
        updated:
          type: string
          format: date-time
        isPublic:
          type: boolean
    IncidentListResponse:
      type: object
      properties:
        totalRows:
          type: integer
        issues:
          type: array
          items:
            $ref: '#/components/schemas/IncidentListItem'
        approvedOrgs:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
              name:
                type: string
    Error:
      type: object
      properties:
        message:
          type: string
  securitySchemes:
    OAuth2BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: OAuth2
      description: 'OAuth2 Scoped Access Token authentication. An authorization header with Bearer token

        must be included with every authenticated request.


        For authentication details, see the official documentation:

        https://kb.armor.com/kb/sso-authentication-with-postman

        '
    FH-AUTH:
      type: http
      scheme: bearer
      bearerFormat: FH-AUTH
      description: 'FH-AUTH token authentication.


        ## Authentication Flow


        1. **Authorize**: POST credentials to `/auth/authorize` to receive an authorization code

        2. **Token Exchange**: Exchange the code at `/auth/token` within 2 minutes for access tokens

        3. **API Calls**: Use the access token in the `Authorization: FH-AUTH {token}` header

        4. **Refresh**: When token expires (15 minutes), refresh via `/auth/token/reissue`


        ## Security Notes


        - Authorization codes expire in 2 minutes

        - Access tokens expire in 15 minutes

        - All endpoints require HTTPS

        - Never log or persist tokens in plain text


        Include the access token in the Authorization header:

        ```

        Authorization: FH-AUTH {access_token}

        ```

        '