Microsoft Defender Alerts API

openapi: 3.1.0
info:
  title: Microsoft Defender for Endpoint Alerts API
  description: API for endpoint detection and response, threat and vulnerability management, and automated investigation and remediation. Provides programmatic access to alerts, machines, and vulnerabilities managed by Microsoft Defender for Endpoint.
  version: 1.0.0
  contact:
    name: Microsoft Defender for Endpoint
    url: https://learn.microsoft.com/en-us/defender-endpoint/api/apis-intro
  license:
    name: Microsoft API Terms of Use
    url: https://www.microsoft.com/en-us/legal/terms-of-use
  x-api-id: microsoft-defender-for-endpoint
servers:
- url: https://api.security.microsoft.com/api
  description: Global production endpoint
- url: https://us.api.security.microsoft.com/api
  description: United States regional endpoint
- url: https://eu.api.security.microsoft.com/api
  description: Europe regional endpoint
- url: https://uk.api.security.microsoft.com/api
  description: United Kingdom regional endpoint
- url: https://au.api.security.microsoft.com/api
  description: Australia regional endpoint
security:
- oauth2: []
tags:
- name: Alerts
  description: Manage security alerts generated by Microsoft Defender for Endpoint. Alerts represent detected threats, suspicious activities, and security events on endpoints.
  externalDocs:
    description: Alerts API documentation
    url: https://learn.microsoft.com/en-us/defender-endpoint/api/alerts
paths:
  /alerts:
    get:
      operationId: listAlerts
      summary: Microsoft Defender List alerts
      description: Retrieves a collection of alerts. Supports OData V4 query parameters including $filter, $top (max 10,000), $skip, and $expand for evidence. Rate limited to 100 calls per minute and 1,500 calls per hour.
      tags:
      - Alerts
      parameters:
      - name: $filter
        in: query
        description: OData filter expression. Filterable properties include alertCreationTime, lastUpdateTime, incidentId, investigationId, id, assignedTo, detectionSource, lastEventTime, status, severity, and category.
        required: false
        schema:
          type: string
        example: severity eq 'High' and status eq 'New'
      - name: $top
        in: query
        description: Maximum number of results to return (max 10,000).
        required: false
        schema:
          type: integer
          maximum: 10000
        example: 10
      - name: $skip
        in: query
        description: Number of results to skip for pagination.
        required: false
        schema:
          type: integer
      - name: $expand
        in: query
        description: Expand related entities. Supports expanding evidence.
        required: false
        schema:
          type: string
          enum:
          - evidence
      responses:
        '200':
          description: A collection of alert objects.
          content:
            application/json:
              schema:
                type: object
                properties:
                  '@odata.context':
                    type: string
                    description: OData context URL.
                  value:
                    type: array
                    items:
                      $ref: '#/components/schemas/Alert'
        '401':
          description: Unauthorized. Invalid or missing authentication token.
        '403':
          description: Forbidden. Insufficient permissions.
        '429':
          description: Too many requests. Rate limit exceeded.
  /alerts/{alertId}:
    get:
      operationId: getAlert
      summary: Microsoft Defender Get alert by ID
      description: Retrieves a specific alert by its alert ID.
      tags:
      - Alerts
      parameters:
      - name: alertId
        in: path
        description: The unique identifier of the alert.
        required: true
        schema:
          type: string
        example: da637472900382838869_1364969609
      responses:
        '200':
          description: The alert object.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Alert'
        '401':
          description: Unauthorized. Invalid or missing authentication token.
        '403':
          description: Forbidden. Insufficient permissions.
        '404':
          description: Alert with the specified ID was not found.
    patch:
      operationId: updateAlert
      summary: Microsoft Defender Update alert
      description: Updates properties of an existing alert. Updatable properties are status, determination, classification, and assignedTo. A comment can be submitted with or without updating properties.
      tags:
      - Alerts
      parameters:
      - name: alertId
        in: path
        description: The unique identifier of the alert to update.
        required: true
        schema:
          type: string
        example: da637472900382838869_1364969609
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AlertUpdate'
      responses:
        '200':
          description: The updated alert object.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Alert'
        '401':
          description: Unauthorized. Invalid or missing authentication token.
        '403':
          description: Forbidden. Insufficient permissions.
        '404':
          description: Alert with the specified ID was not found.
  /machines/{machineId}/alerts:
    get:
      operationId: listMachineAlerts
      summary: Microsoft Defender List alerts for a machine
      description: Retrieves a collection of alerts related to a specific machine.
      tags:
      - Alerts
      parameters:
      - name: machineId
        in: path
        description: The device ID of the machine.
        required: true
        schema:
          type: string
        example: 1e5bc9d7e413ddd7902c2932e418702b84d0cc07
      responses:
        '200':
          description: A collection of alert objects for the specified machine.
          content:
            application/json:
              schema:
                type: object
                properties:
                  '@odata.context':
                    type: string
                  value:
                    type: array
                    items:
                      $ref: '#/components/schemas/Alert'
        '401':
          description: Unauthorized.
        '403':
          description: Forbidden.
        '404':
          description: Machine not found.
components:
  schemas:
    RelatedUser:
      type: object
      description: Details of a user related to an alert.
      properties:
        userName:
          type: string
          description: The user name.
        domainName:
          type: string
          description: The domain name.
    AlertEvidence:
      type: object
      description: Evidence associated with an alert. Can represent various entity types including User, Process, File, IP address, and URL.
      properties:
        entityType:
          type: string
          description: The type of evidence entity.
          enum:
          - User
          - Process
          - File
          - Ip
          - Url
        evidenceCreationTime:
          type:
          - string
          - 'null'
          format: date-time
          description: The time the evidence was created.
        sha1:
          type:
          - string
          - 'null'
          description: SHA-1 hash of the file.
        sha256:
          type:
          - string
          - 'null'
          description: SHA-256 hash of the file.
        fileName:
          type:
          - string
          - 'null'
          description: The file name.
        filePath:
          type:
          - string
          - 'null'
          description: The file path.
        processId:
          type:
          - integer
          - 'null'
          description: The process ID.
        processCommandLine:
          type:
          - string
          - 'null'
          description: The process command line.
        processCreationTime:
          type:
          - string
          - 'null'
          format: date-time
          description: The process creation time.
        parentProcessId:
          type:
          - integer
          - 'null'
          description: The parent process ID.
        parentProcessCreationTime:
          type:
          - string
          - 'null'
          format: date-time
          description: The parent process creation time.
        parentProcessFileName:
          type:
          - string
          - 'null'
          description: The parent process file name.
        parentProcessFilePath:
          type:
          - string
          - 'null'
          description: The parent process file path.
        ipAddress:
          type:
          - string
          - 'null'
          description: The IP address.
        url:
          type:
          - string
          - 'null'
          description: The URL.
        registryKey:
          type:
          - string
          - 'null'
          description: The registry key.
        registryHive:
          type:
          - string
          - 'null'
          description: The registry hive.
        registryValueType:
          type:
          - string
          - 'null'
          description: The registry value type.
        registryValue:
          type:
          - string
          - 'null'
          description: The registry value.
        accountName:
          type:
          - string
          - 'null'
          description: The account name.
        domainName:
          type:
          - string
          - 'null'
          description: The domain name.
        userSid:
          type:
          - string
          - 'null'
          description: The user security identifier (SID).
        aadUserId:
          type:
          - string
          - 'null'
          description: The Microsoft Entra user ID.
        userPrincipalName:
          type:
          - string
          - 'null'
          description: The user principal name.
        detectionStatus:
          type:
          - string
          - 'null'
          description: The detection status of the evidence.
          enum:
          - Detected
          - Blocked
          - Prevented
          - null
    Alert:
      type: object
      description: Represents a security alert generated by Microsoft Defender for Endpoint, indicating a detected threat, suspicious activity, or security event on an endpoint.
      properties:
        id:
          type: string
          description: The unique identifier for the alert.
          examples:
          - da637472900382838869_1364969609
        title:
          type: string
          description: A brief title summarizing the alert.
          examples:
          - Low-reputation arbitrary code executed by signed executable
        description:
          type: string
          description: A detailed description of the alert and its context.
        alertCreationTime:
          type:
          - string
          - 'null'
          format: date-time
          description: The date and time (in UTC) the alert was created.
        lastEventTime:
          type:
          - string
          - 'null'
          format: date-time
          description: The last occurrence of the event that triggered the alert on the same device.
        firstEventTime:
          type:
          - string
          - 'null'
          format: date-time
          description: The first occurrence of the event that triggered the alert on that device.
        lastUpdateTime:
          type:
          - string
          - 'null'
          format: date-time
          description: The date and time (in UTC) the alert was last updated.
        resolvedTime:
          type:
          - string
          - 'null'
          format: date-time
          description: The date and time when the status of the alert was changed to Resolved.
        incidentId:
          type:
          - integer
          - 'null'
          format: int64
          description: The incident ID associated with the alert.
        investigationId:
          type:
          - integer
          - 'null'
          format: int64
          description: The investigation ID related to the alert.
        investigationState:
          type:
          - string
          - 'null'
          description: The current state of the investigation.
          enum:
          - Unknown
          - Terminated
          - SuccessfullyRemediated
          - Benign
          - Failed
          - PartiallyRemediated
          - Running
          - PendingApproval
          - PendingResource
          - PartiallyInvestigated
          - TerminatedByUser
          - TerminatedBySystem
          - Queued
          - InnerFailure
          - PreexistingAlert
          - UnsupportedOs
          - UnsupportedAlertType
          - SuppressedAlert
          - null
        assignedTo:
          type:
          - string
          - 'null'
          description: The owner (assignee) of the alert.
        rbacGroupName:
          type:
          - string
          - 'null'
          description: The role-based access control device group name.
        mitreTechniques:
          type: array
          items:
            type: string
          description: MITRE ATT&CK Enterprise technique IDs associated with the alert.
          examples:
          - - T1064
            - T1085
            - T1220
        relatedUser:
          $ref: '#/components/schemas/RelatedUser'
        severity:
          type: string
          description: The severity level of the alert.
          enum:
          - UnSpecified
          - Informational
          - Low
          - Medium
          - High
        status:
          type: string
          description: The current status of the alert.
          enum:
          - Unknown
          - New
          - InProgress
          - Resolved
        classification:
          type:
          - string
          - 'null'
          description: The classification of the alert.
          enum:
          - TruePositive
          - InformationalExpectedActivity
          - FalsePositive
          - null
        determination:
          type:
          - string
          - 'null'
          description: The determination of the alert.
          enum:
          - MultiStagedAttack
          - MaliciousUserActivity
          - CompromisedUser
          - Malware
          - Phishing
          - UnwantedSoftware
          - SecurityTesting
          - LineOfBusinessApplication
          - ConfirmedActivity
          - NotMalicious
          - InsufficientData
          - Other
          - null
        category:
          type:
          - string
          - 'null'
          description: The category of the alert.
          examples:
          - Execution
          - SuspiciousActivity
        detectionSource:
          type:
          - string
          - 'null'
          description: The source that detected the alert.
          examples:
          - WindowsDefenderAtp
          - WindowsDefenderAv
        threatFamilyName:
          type:
          - string
          - 'null'
          description: The threat family name associated with the alert.
        threatName:
          type:
          - string
          - 'null'
          description: The specific threat name.
        machineId:
          type:
          - string
          - 'null'
          description: The ID of the machine entity associated with the alert.
        computerDnsName:
          type:
          - string
          - 'null'
          description: The fully qualified domain name of the machine.
        aadTenantId:
          type:
          - string
          - 'null'
          description: The Microsoft Entra tenant ID.
        detectorId:
          type:
          - string
          - 'null'
          description: The ID of the detector that triggered the alert.
        comments:
          type: array
          items:
            $ref: '#/components/schemas/AlertComment'
          description: Comments associated with the alert.
        evidence:
          type: array
          items:
            $ref: '#/components/schemas/AlertEvidence'
          description: Evidence related to the alert.
    AlertUpdate:
      type: object
      description: Request body for updating an alert.
      properties:
        status:
          type: string
          description: The new status for the alert.
          enum:
          - New
          - InProgress
          - Resolved
        assignedTo:
          type: string
          description: The new owner of the alert.
        classification:
          type: string
          description: The classification of the alert.
          enum:
          - TruePositive
          - InformationalExpectedActivity
          - FalsePositive
        determination:
          type: string
          description: The determination of the alert.
          enum:
          - MultiStagedAttack
          - MaliciousUserActivity
          - CompromisedUser
          - Malware
          - Phishing
          - UnwantedSoftware
          - SecurityTesting
          - LineOfBusinessApplication
          - ConfirmedActivity
          - NotMalicious
          - InsufficientData
          - Other
        comment:
          type: string
          description: A comment to add to the alert.
    AlertComment:
      type: object
      description: A comment associated with an alert.
      properties:
        comment:
          type: string
          description: The comment text.
        createdBy:
          type: string
          description: The user who created the comment.
        createdTime:
          type: string
          format: date-time
          description: The date and time the comment was created.
  securitySchemes:
    oauth2:
      type: oauth2
      description: OAuth 2.0 authentication using Microsoft Entra ID (Azure AD). Supports both application-level and delegated permissions.
      flows:
        clientCredentials:
          tokenUrl: https://login.microsoftonline.com/{tenantId}/oauth2/v2.0/token
          scopes:
            https://api.security.microsoft.com/.default: Default scope for application permissions
        authorizationCode:
          authorizationUrl: https://login.microsoftonline.com/{tenantId}/oauth2/v2.0/authorize
          tokenUrl: https://login.microsoftonline.com/{tenantId}/oauth2/v2.0/token
          scopes:
            https://api.security.microsoft.com/.default: Default scope for delegated permissions
externalDocs:
  description: Microsoft Defender for Endpoint API documentation
  url: https://learn.microsoft.com/en-us/defender-endpoint/api/apis-intro