openapi: 3.1.0
info:
title: Microsoft Defender for Endpoint 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
- name: Machines
description: >-
Manage devices (machines) that have communicated with Microsoft
Defender for Endpoint. Retrieve device information, health status,
risk scores, and exposure levels.
externalDocs:
description: Machines API documentation
url: https://learn.microsoft.com/en-us/defender-endpoint/api/machine
- name: Vulnerabilities
description: >-
Retrieve vulnerability information from Microsoft Defender Vulnerability
Management. Access CVE data, severity scores, exploit information,
and exposure metrics.
externalDocs:
description: Vulnerabilities API documentation
url: https://learn.microsoft.com/en-us/defender-endpoint/api/vulnerability
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:
get:
operationId: listMachines
summary: Microsoft Defender List machines
description: >-
Retrieves a collection of machines that have communicated with
Microsoft Defender for Endpoint. Supports OData V4 query parameters
including $filter, $top (max 10,000), and $skip. Rate limited to
100 calls per minute and 1,500 calls per hour.
tags:
- Machines
parameters:
- name: $filter
in: query
description: >-
OData filter expression. Filterable properties include
computerDnsName, id, version, deviceValue, aadDeviceId,
machineTags, lastSeen, exposureLevel, onboardingStatus,
lastIpAddress, healthStatus, osPlatform, riskScore,
and rbacGroupId.
required: false
schema:
type: string
example: healthStatus eq 'Active' and riskScore eq 'High'
- name: $top
in: query
description: Maximum number of results to return (max 10,000).
required: false
schema:
type: integer
maximum: 10000
example: 50
- name: $skip
in: query
description: Number of results to skip for pagination.
required: false
schema:
type: integer
responses:
'200':
description: A collection of machine objects.
content:
application/json:
schema:
type: object
properties:
'@odata.context':
type: string
description: OData context URL.
value:
type: array
items:
$ref: '#/components/schemas/Machine'
'401':
description: Unauthorized. Invalid or missing authentication token.
'403':
description: Forbidden. Insufficient permissions.
'404':
description: No recent machines found.
'429':
description: Too many requests. Rate limit exceeded.
/machines/{machineId}:
get:
operationId: getMachine
summary: Microsoft Defender Get machine by ID
description: >-
Retrieves a specific machine by its device ID or computer name.
tags:
- Machines
parameters:
- name: machineId
in: path
description: The device ID or computer name of the machine.
required: true
schema:
type: string
example: 1e5bc9d7e413ddd7902c2932e418702b84d0cc07
responses:
'200':
description: The machine object.
content:
application/json:
schema:
$ref: '#/components/schemas/Machine'
'401':
description: Unauthorized. Invalid or missing authentication token.
'403':
description: Forbidden. Insufficient permissions.
'404':
description: Machine 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
- Machines
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.
/machines/{machineId}/vulnerabilities:
get:
operationId: listMachineVulnerabilities
summary: Microsoft Defender List vulnerabilities for a machine
description: >-
Retrieves a collection of discovered vulnerabilities related to
a specific machine.
tags:
- Machines
- Vulnerabilities
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 vulnerability objects for the machine.
content:
application/json:
schema:
type: object
properties:
'@odata.context':
type: string
value:
type: array
items:
$ref: '#/components/schemas/Vulnerability'
'401':
description: Unauthorized.
'403':
description: Forbidden.
'404':
description: Machine not found.
/vulnerabilities:
get:
operationId: listVulnerabilities
summary: Microsoft Defender List all vulnerabilities
description: >-
Retrieves a list of all vulnerabilities affecting the organization.
Supports OData V4 query parameters including $filter, $top
(max 8,000), and $skip.
tags:
- Vulnerabilities
parameters:
- name: $filter
in: query
description: >-
OData filter expression. Filterable properties include id,
name, description, cvssV3, publishedOn, severity, and updatedOn.
required: false
schema:
type: string
example: severity eq 'Critical'
- name: $top
in: query
description: Maximum number of results to return (max 8,000).
required: false
schema:
type: integer
maximum: 8000
example: 50
- name: $skip
in: query
description: Number of results to skip for pagination.
required: false
schema:
type: integer
responses:
'200':
description: A collection of vulnerability objects.
content:
application/json:
schema:
type: object
properties:
'@odata.context':
type: string
description: OData context URL.
value:
type: array
items:
$ref: '#/components/schemas/Vulnerability'
'401':
description: Unauthorized. Invalid or missing authentication token.
'403':
description: Forbidden. Insufficient permissions.
'429':
description: Too many requests. Rate limit exceeded.
/vulnerabilities/{vulnerabilityId}:
get:
operationId: getVulnerability
summary: Microsoft Defender Get vulnerability by ID
description: Retrieves a specific vulnerability by its CVE ID.
tags:
- Vulnerabilities
parameters:
- name: vulnerabilityId
in: path
description: The CVE identifier of the vulnerability.
required: true
schema:
type: string
example: CVE-2024-7256
responses:
'200':
description: The vulnerability object.
content:
application/json:
schema:
$ref: '#/components/schemas/Vulnerability'
'401':
description: Unauthorized.
'403':
description: Forbidden.
'404':
description: Vulnerability not found.
/vulnerabilities/{vulnerabilityId}/machineReferences:
get:
operationId: listVulnerabilityMachineReferences
summary: Microsoft Defender List machines affected by a vulnerability
description: >-
Retrieves a list of machines affected by a specific vulnerability.
tags:
- Machines
- Vulnerabilities
parameters:
- name: vulnerabilityId
in: path
description: The CVE identifier of the vulnerability.
required: true
schema:
type: string
example: CVE-2024-7256
responses:
'200':
description: A collection of machine references for the vulnerability.
content:
application/json:
schema:
type: object
properties:
'@odata.context':
type: string
value:
type: array
items:
$ref: '#/components/schemas/MachineReference'
'401':
description: Unauthorized.
'403':
description: Forbidden.
'404':
description: Vulnerability not found.
components:
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
schemas:
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
-
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
-
determination:
type:
- string
- 'null'
description: The determination of the alert.
enum:
- MultiStagedAttack
- MaliciousUserActivity
- CompromisedUser
- Malware
- Phishing
- UnwantedSoftware
- SecurityTesting
- LineOfBusinessApplication
- ConfirmedActivity
- NotMalicious
- InsufficientData
- Other
-
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.
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.
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
-
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.
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.
Machine:
type: object
description: >-
Represents a device (machine) that has communicated with Microsoft
Defender for Endpoint, including its health status, risk assessment,
and configuration details.
properties:
id:
type: string
description: The unique machine identity.
examples:
- 1e5bc9d7e413ddd7902c2932e418702b84d0cc07
computerDnsName:
type: string
description: The fully qualified domain name of the machine.
examples:
- mymachine1.contoso.com
firstSeen:
type: string
format: date-time
description: >-
The first date and time where the machine was observed by
Microsoft Defender for Endpoint.
lastSeen:
type: string
format: date-time
description: >-
The time and date of the last received full device report.
A device typically sends a full report every 24 hours.
osPlatform:
type: string
description: The operating system platform.
examples:
- Windows10
- Windows11
- Linux
onboardingStatus:
type: string
description: The onboarding status of the machine.
enum:
- Onboarded
- CanBeOnboarded
- Unsupported
- InsufficientInfo
osProcessor:
type: string
description: >-
The operating system processor. Deprecated in favor of
osArchitecture.
deprecated: true
version:
type:
- string
- 'null'
description: The operating system version.
osBuild:
type:
- integer
- 'null'
format: int64
description: The operating system build number.
lastIpAddress:
type:
- string
- 'null'
description: The last IP address on the local NIC of the machine.
lastExternalIpAddress:
type:
- string
- 'null'
description: >-
The last IP address through which the machine accessed the
internet.
healthStatus:
type: string
description: The machine health status.
enum:
- Active
- Inactive
- ImpairedCommunication
- NoSensorData
- NoSensorDataImpairedCommunication
- Unknown
rbacGroupName:
type:
- string
- 'null'
description: The machine group name.
rbacGroupId:
type:
- integer
- 'null'
description: The machine group ID.
riskScore:
type:
- string
- 'null'
description: >-
The risk score as evaluated by Microsoft Defender for Endpoint.
enum:
- None
- Informational
- Low
- Medium
- High
-
aadDeviceId:
type:
- string
- 'null'
format: uuid
description: >-
The Microsoft Entra Device ID (when the machine is Microsoft
Entra joined).
machineTags:
type: array
items:
type: string
description: Set of machine tags.
exposureLevel:
type:
- string
- 'null'
description: >-
The exposure level as evaluated by Microsoft Defender for
Endpoint.
enum:
- None
- Low
- Medium
- High
-
deviceValue:
type:
- string
- 'null'
description: The value of the device.
enum:
- Normal
- Low
- High
-
ipAddresses:
type: array
items:
$ref: '#/components/schemas/IpAddress'
description: Set of IP address o
# --- truncated at 32 KB (36 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/microsoft-defender/refs/heads/main/openapi/microsoft-defender-for-endpoint-api-openapi.yml