Microsoft Graph Security is a unified set of APIs within Microsoft Graph that lets you access, correlate, and act on security data across Microsoft 365 and integrated security solutions. It normalizes alerts and incidents from Microsoft Defender products and other providers, exposes security posture information such as Secure Score, and supports managing threat intelligence indicators.
openapi: 3.1.0
info:
title: Microsoft Graph Security
description: Needs a description.
paths:
/reports/security:
description: >-
Provides operations to manage the security property of the
microsoft.graph.reportRoot entity.
get:
tags:
- reports.securityReportsRoot
summary: Microsoft Graph Get security from reports
description: >-
Represents an abstract type that contains resources for attack
simulation and training reports.
operationId: reports.GetSecurity
parameters:
- name: $select
in: query
description: Select properties to be returned
style: form
explode: false
schema:
uniqueItems: true
type: array
items:
type: string
- name: $expand
in: query
description: Expand related entities
style: form
explode: false
schema:
uniqueItems: true
type: array
items:
type: string
responses:
2XX:
description: Retrieved navigation property
content:
application/json:
schema:
$ref: '#/components/schemas/microsoft.graph.securityReportsRoot'
4XX:
$ref: '#/components/responses/error'
5XX:
$ref: '#/components/responses/error'
x-ms-docs-operation-type: operation
patch:
tags:
- reports.securityReportsRoot
summary: Microsoft Graph Update the navigation property security in reports
operationId: reports.UpdateSecurity
requestBody:
description: New navigation property values
content:
application/json:
schema:
$ref: '#/components/schemas/microsoft.graph.securityReportsRoot'
required: true
responses:
2XX:
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/microsoft.graph.securityReportsRoot'
4XX:
$ref: '#/components/responses/error'
5XX:
$ref: '#/components/responses/error'
x-ms-docs-operation-type: operation
delete:
tags:
- reports.securityReportsRoot
summary: Microsoft Graph Delete navigation property security for reports
operationId: reports.DeleteSecurity
parameters:
- name: If-Match
in: header
description: ETag
schema:
type: string
responses:
'204':
description: Success
4XX:
$ref: '#/components/responses/error'
5XX:
$ref: '#/components/responses/error'
x-ms-docs-operation-type: operation
/reports/security/getAttackSimulationRepeatOffenders():
description: Provides operations to call the getAttackSimulationRepeatOffenders method.
get:
tags:
- reports.securityReportsRoot
summary: Microsoft Graph Invoke function getAttackSimulationRepeatOffenders
description: >-
List the tenant users who have yielded to attacks more than once in
attack simulation and training campaigns. This function supports
@odata.nextLink for pagination.
externalDocs:
description: Find more info here
url: >-
https://learn.microsoft.com/graph/api/securityreportsroot-getattacksimulationrepeatoffenders?view=graph-rest-1.0
operationId: reports.security.getAttackSimulationRepeatOffenders
parameters:
- $ref: '#/components/parameters/top'
- $ref: '#/components/parameters/skip'
- $ref: '#/components/parameters/search'
- $ref: '#/components/parameters/filter'
- $ref: '#/components/parameters/count'
responses:
2XX:
description: Success
content:
application/json:
schema:
type: object
allOf:
- $ref: '#/components/schemas/BaseCollectionPaginationCountResponse'
- type: object
properties:
value:
type: array
items:
$ref: >-
#/components/schemas/microsoft.graph.attackSimulationRepeatOffender
4XX:
$ref: '#/components/responses/error'
5XX:
$ref: '#/components/responses/error'
x-ms-docs-operation-type: function
x-ms-pageable:
nextLinkName: '@odata.nextLink'
operationName: listMore
/reports/security/getAttackSimulationSimulationUserCoverage():
description: >-
Provides operations to call the getAttackSimulationSimulationUserCoverage
method.
get:
tags:
- reports.securityReportsRoot
summary: Microsoft Graph Invoke function getAttackSimulationSimulationUserCoverage
description: >-
List training coverage for each tenant user in attack simulation and
training campaigns. This function supports @odata.nextLink for
pagination.
externalDocs:
description: Find more info here
url: >-
https://learn.microsoft.com/graph/api/securityreportsroot-getattacksimulationsimulationusercoverage?view=graph-rest-1.0
operationId: reports.security.getAttackSimulationSimulationUserCoverage
parameters:
- $ref: '#/components/parameters/top'
- $ref: '#/components/parameters/skip'
- $ref: '#/components/parameters/search'
- $ref: '#/components/parameters/filter'
- $ref: '#/components/parameters/count'
responses:
2XX:
description: Success
content:
application/json:
schema:
type: object
allOf:
- $ref: '#/components/schemas/BaseCollectionPaginationCountResponse'
- type: object
properties:
value:
type: array
items:
$ref: >-
#/components/schemas/microsoft.graph.attackSimulationSimulationUserCoverage
4XX:
$ref: '#/components/responses/error'
5XX:
$ref: '#/components/responses/error'
x-ms-docs-operation-type: function
x-ms-pageable:
nextLinkName: '@odata.nextLink'
operationName: listMore
/reports/security/getAttackSimulationTrainingUserCoverage():
description: >-
Provides operations to call the getAttackSimulationTrainingUserCoverage
method.
get:
tags:
- reports.securityReportsRoot
summary: Microsoft Graph Invoke function getAttackSimulationTrainingUserCoverage
description: >-
List training coverage for tenant users in attack simulation and
training campaigns. This function supports @odata.nextLink for
pagination.
externalDocs:
description: Find more info here
url: >-
https://learn.microsoft.com/graph/api/securityreportsroot-getattacksimulationtrainingusercoverage?view=graph-rest-1.0
operationId: reports.security.getAttackSimulationTrainingUserCoverage
parameters:
- $ref: '#/components/parameters/top'
- $ref: '#/components/parameters/skip'
- $ref: '#/components/parameters/search'
- $ref: '#/components/parameters/filter'
- $ref: '#/components/parameters/count'
responses:
2XX:
description: Success
content:
application/json:
schema:
type: object
allOf:
- $ref: '#/components/schemas/BaseCollectionPaginationCountResponse'
- type: object
properties:
value:
type: array
items:
$ref: >-
#/components/schemas/microsoft.graph.attackSimulationTrainingUserCoverage
4XX:
$ref: '#/components/responses/error'
5XX:
$ref: '#/components/responses/error'
x-ms-docs-operation-type: function
x-ms-pageable:
nextLinkName: '@odata.nextLink'
operationName: listMore
/security:
description: Provides operations to manage the security singleton.
get:
tags:
- Security.security
summary: Microsoft Graph Get security
operationId: security.security.GetSecurity
parameters:
- name: $select
in: query
description: Select properties to be returned
style: form
explode: false
schema:
uniqueItems: true
type: array
items:
type: string
- name: $expand
in: query
description: Expand related entities
style: form
explode: false
schema:
uniqueItems: true
type: array
items:
type: string
responses:
2XX:
description: Retrieved entity
content:
application/json:
schema:
$ref: '#/components/schemas/microsoft.graph.security'
4XX:
$ref: '#/components/responses/error'
5XX:
$ref: '#/components/responses/error'
x-ms-docs-operation-type: operation
patch:
tags:
- Security.security
summary: Microsoft Graph Update security
operationId: security.security.UpdateSecurity
requestBody:
description: New property values
content:
application/json:
schema:
$ref: '#/components/schemas/microsoft.graph.security'
required: true
responses:
2XX:
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/microsoft.graph.security'
4XX:
$ref: '#/components/responses/error'
5XX:
$ref: '#/components/responses/error'
x-ms-docs-operation-type: operation
/security/alerts:
description: >-
Provides operations to manage the alerts property of the
microsoft.graph.security entity.
get:
tags:
- Security.alert
summary: Microsoft Graph List alerts
description: Retrieve a list of alert objects.
externalDocs:
description: Find more info here
url: https://learn.microsoft.com/graph/api/alert-list?view=graph-rest-1.0
operationId: security.ListAlerts
parameters:
- $ref: '#/components/parameters/top'
- $ref: '#/components/parameters/skip'
- $ref: '#/components/parameters/search'
- $ref: '#/components/parameters/filter'
- $ref: '#/components/parameters/count'
- name: $orderby
in: query
description: Order items by property values
style: form
explode: false
schema:
uniqueItems: true
type: array
items:
type: string
- name: $select
in: query
description: Select properties to be returned
style: form
explode: false
schema:
uniqueItems: true
type: array
items:
type: string
- name: $expand
in: query
description: Expand related entities
style: form
explode: false
schema:
uniqueItems: true
type: array
items:
type: string
responses:
2XX:
$ref: '#/components/responses/microsoft.graph.alertCollectionResponse'
4XX:
$ref: '#/components/responses/error'
5XX:
$ref: '#/components/responses/error'
deprecated: true
x-ms-deprecation:
removalDate: '2026-04-10'
date: '2024-04-10'
version: 2024-01/Deprecation
description: >-
The legacy Graph Security API is deprecated and will stop returning
data on January 31, 2025. Please use the new Graph Security API.
x-ms-pageable:
nextLinkName: '@odata.nextLink'
operationName: listMore
x-ms-docs-operation-type: operation
post:
tags:
- Security.alert
summary: Microsoft Graph Create new navigation property to alerts for security
operationId: security.CreateAlerts
requestBody:
description: New navigation property
content:
application/json:
schema:
$ref: '#/components/schemas/microsoft.graph.alert'
required: true
responses:
2XX:
description: Created navigation property.
content:
application/json:
schema:
$ref: '#/components/schemas/microsoft.graph.alert'
4XX:
$ref: '#/components/responses/error'
5XX:
$ref: '#/components/responses/error'
deprecated: true
x-ms-deprecation:
removalDate: '2026-04-10'
date: '2024-04-10'
version: 2024-01/Deprecation
description: >-
The legacy Graph Security API is deprecated and will stop returning
data on January 31, 2025. Please use the new Graph Security API.
x-ms-docs-operation-type: operation
/security/alerts_v2:
description: >-
Provides operations to manage the alerts_v2 property of the
microsoft.graph.security entity.
get:
tags:
- Security.alert
summary: Microsoft Graph List alerts_v2
description: >-
Get a list of alert resources created to track suspicious activities in
an organization. This operation lets you filter and sort through alerts
to create an informed cyber security response. It exposes a collection
of alerts that were flagged in your network, within the time range you
specified in your environment retention policy. The most recent alerts
are displayed at the top of the list.
externalDocs:
description: Find more info here
url: >-
https://learn.microsoft.com/graph/api/security-list-alerts_v2?view=graph-rest-1.0
operationId: security.ListAlerts_v2
parameters:
- $ref: '#/components/parameters/top'
- $ref: '#/components/parameters/skip'
- $ref: '#/components/parameters/search'
- $ref: '#/components/parameters/filter'
- $ref: '#/components/parameters/count'
- name: $orderby
in: query
description: Order items by property values
style: form
explode: false
schema:
uniqueItems: true
type: array
items:
type: string
- name: $select
in: query
description: Select properties to be returned
style: form
explode: false
schema:
uniqueItems: true
type: array
items:
type: string
- name: $expand
in: query
description: Expand related entities
style: form
explode: false
schema:
uniqueItems: true
type: array
items:
type: string
responses:
2XX:
$ref: >-
#/components/responses/microsoft.graph.security.alertCollectionResponse
4XX:
$ref: '#/components/responses/error'
5XX:
$ref: '#/components/responses/error'
x-ms-pageable:
nextLinkName: '@odata.nextLink'
operationName: listMore
x-ms-docs-operation-type: operation
post:
tags:
- Security.alert
summary: Microsoft Graph Create new navigation property to alerts_v2 for security
operationId: security.CreateAlerts_v2
requestBody:
description: New navigation property
content:
application/json:
schema:
$ref: '#/components/schemas/microsoft.graph.security.alert'
required: true
responses:
2XX:
description: Created navigation property.
content:
application/json:
schema:
$ref: '#/components/schemas/microsoft.graph.security.alert'
4XX:
$ref: '#/components/responses/error'
5XX:
$ref: '#/components/responses/error'
x-ms-docs-operation-type: operation
/security/alerts_v2/{alert-id}:
description: >-
Provides operations to manage the alerts_v2 property of the
microsoft.graph.security entity.
get:
tags:
- Security.alert
summary: Microsoft Graph Get alert
description: Get the properties and relationships of an alert object.
externalDocs:
description: Find more info here
url: >-
https://learn.microsoft.com/graph/api/security-alert-get?view=graph-rest-1.0
operationId: security.GetAlerts_v2
parameters:
- name: $select
in: query
description: Select properties to be returned
style: form
explode: false
schema:
uniqueItems: true
type: array
items:
type: string
- name: $expand
in: query
description: Expand related entities
style: form
explode: false
schema:
uniqueItems: true
type: array
items:
type: string
responses:
2XX:
description: Retrieved navigation property
content:
application/json:
schema:
$ref: '#/components/schemas/microsoft.graph.security.alert'
4XX:
$ref: '#/components/responses/error'
5XX:
$ref: '#/components/responses/error'
x-ms-docs-operation-type: operation
patch:
tags:
- Security.alert
summary: Microsoft Graph Update alert
description: >-
Update the properties of an alert object in an organization based on the
specified alert id property.
externalDocs:
description: Find more info here
url: >-
https://learn.microsoft.com/graph/api/security-alert-update?view=graph-rest-1.0
operationId: security.UpdateAlerts_v2
requestBody:
description: New navigation property values
content:
application/json:
schema:
$ref: '#/components/schemas/microsoft.graph.security.alert'
required: true
responses:
2XX:
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/microsoft.graph.security.alert'
4XX:
$ref: '#/components/responses/error'
5XX:
$ref: '#/components/responses/error'
x-ms-docs-operation-type: operation
delete:
tags:
- Security.alert
summary: Microsoft Graph Delete navigation property alerts_v2 for security
operationId: security.DeleteAlerts_v2
parameters:
- name: If-Match
in: header
description: ETag
schema:
type: string
responses:
'204':
description: Success
4XX:
$ref: '#/components/responses/error'
5XX:
$ref: '#/components/responses/error'
x-ms-docs-operation-type: operation
parameters:
- name: alert-id
in: path
description: The unique identifier of alert
required: true
schema:
type: string
x-ms-docs-key-type: alert
/security/alerts_v2/{alert-id}/comments:
post:
tags:
- Security.alert
summary: Microsoft Graph Create comment for alert
description: >-
Create a comment for an existing alert based on the specified alert id
property.
externalDocs:
description: Find more info here
url: >-
https://learn.microsoft.com/graph/api/security-alert-post-comments?view=graph-rest-1.0
operationId: security.alerts_v2.SetComments
parameters:
- name: If-Match
in: header
description: ETag
schema:
type: string
requestBody:
description: New property values
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/microsoft.graph.security.alertComment'
required: true
responses:
2XX:
description: Success
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/microsoft.graph.security.alertComment'
4XX:
$ref: '#/components/responses/error'
5XX:
$ref: '#/components/responses/error'
parameters:
- name: alert-id
in: path
description: The unique identifier of alert
required: true
schema:
type: string
x-ms-docs-key-type: alert
/security/alerts_v2/{alert-id}/comments/$count:
description: Provides operations to count the resources in the collection.
get:
tags:
- Security.alert
summary: Microsoft Graph Get the number of the resource
operationId: security.alerts_v2.Comments.GetCount-2f70
parameters:
- $ref: '#/components/parameters/search'
- $ref: '#/components/parameters/filter'
responses:
2XX:
$ref: '#/components/responses/ODataCountResponse'
4XX:
$ref: '#/components/responses/error'
5XX:
$ref: '#/components/responses/error'
parameters:
- name: alert-id
in: path
description: The unique identifier of alert
required: true
schema:
type: string
x-ms-docs-key-type: alert
/security/alerts_v2/$count:
description: Provides operations to count the resources in the collection.
get:
tags:
- Security.alert
summary: Microsoft Graph Get the number of the resource
operationId: security.alerts_v2.GetCount-9522
parameters:
- $ref: '#/components/parameters/search'
- $ref: '#/components/parameters/filter'
responses:
2XX:
$ref: '#/components/responses/ODataCountResponse'
4XX:
$ref: '#/components/responses/error'
5XX:
$ref: '#/components/responses/error'
/security/alerts/{alert-id}:
description: >-
Provides operations to manage the alerts property of the
microsoft.graph.security entity.
get:
tags:
- Security.alert
summary: Microsoft Graph Get alert
description: Retrieve the properties and relationships of an alert object.
externalDocs:
description: Find more info here
url: https://learn.microsoft.com/graph/api/alert-get?view=graph-rest-1.0
operationId: security.GetAlerts
parameters:
- name: $select
in: query
description: Select properties to be returned
style: form
explode: false
schema:
uniqueItems: true
type: array
items:
type: string
- name: $expand
in: query
description: Expand related entities
style: form
explode: false
schema:
uniqueItems: true
type: array
items:
type: string
responses:
2XX:
description: Retrieved navigation property
content:
application/json:
schema:
$ref: '#/components/schemas/microsoft.graph.alert'
4XX:
$ref: '#/components/responses/error'
5XX:
$ref: '#/components/responses/error'
deprecated: true
x-ms-deprecation:
removalDate: '2026-04-10'
date: '2024-04-10'
version: 2024-01/Deprecation
description: >-
The legacy Graph Security API is deprecated and will stop returning
data on January 31, 2025. Please use the new Graph Security API.
x-ms-docs-operation-type: operation
patch:
tags:
- Security.alert
summary: Microsoft Graph Update alert
description: >-
Update an editable alert property within any integrated solution to keep
alert status and assignments in sync across solutions. This method
updates any solution that has a record of the referenced alert ID.
externalDocs:
description: Find more info here
url: https://learn.microsoft.com/graph/api/alert-update?view=graph-rest-1.0
operationId: security.UpdateAlerts
requestBody:
description: New navigation property values
content:
application/json:
schema:
$ref: '#/components/schemas/microsoft.graph.alert'
required: true
responses:
2XX:
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/microsoft.graph.alert'
4XX:
$ref: '#/components/responses/error'
5XX:
$ref: '#/components/responses/error'
deprecated: true
x-ms-deprecation:
removalDate: '2026-04-10'
date: '2024-04-10'
version: 2024-01/Deprecation
description: >-
The legacy Graph Security API is deprecated and will stop returning
data on January 31, 2025. Please use the new Graph Security API.
x-ms-docs-operation-type: operation
parameters:
- name: alert-id
in: path
description: The unique identifier of alert
required: true
schema:
type: string
x-ms-docs-key-type: alert
/security/alerts/$count:
description: Provides operations to count the resources in the collection.
get:
tags:
- Security.alert
summary: Microsoft Graph Get the number of the resource
operationId: security.alerts.GetCount-82d4
parameters:
- $ref: '#/components/parameters/search'
- $ref: '#/components/parameters/filter'
responses:
2XX:
$ref: '#/components/responses/ODataCountResponse'
4XX:
$ref: '#/components/responses/error'
5XX:
$ref: '#/components/responses/error'
deprecated: true
x-ms-deprecation:
removalDate: '2026-04-10'
date: '2024-04-10'
version: 2024-01/Deprecation
description: >-
The legacy Graph Security API is deprecated and will stop returning
data on January 31, 2025. Please use the new Graph Security API.
/security/attackSimulation:
description: >-
Provides operations to manage the attackSimulation property of the
microsoft.graph.security entity.
get:
tags:
- security.attackSimulationRoot
summary: Microsoft Graph Get attackSimulation from security
operationId: security.GetAttackSimulation
parameters:
- name: $select
in: query
description: Select properties to be returned
style: form
explode: false
schema:
uniqueItems: true
type: array
items:
type: string
- name: $expand
in: query
description: Expand related entities
style: form
explode: false
schema:
uniqueItems: true
type: array
items:
type: string
responses:
2XX:
description: Retrieved navigation property
content:
application/json:
schema:
$ref: '#/components/schemas/microsoft.graph.attackSimulationRoot'
4XX:
$ref: '#/components/responses/error'
5XX:
$ref: '#/components/responses/error'
x-ms-docs-operation-type: operation
patch:
tags:
- security.attackSimulationRoot
summary: Microsoft Graph Update the navigation property attackSimulation in security
operationId: security.UpdateAttackSimulation
requestBody:
description: New navigation property values
content:
application/json:
schema:
$ref: '#/components/schemas/microsoft.graph.attackSimulationRoot'
required: true
responses:
2XX:
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/microsoft.graph.attackSimulationRoot'
4XX:
$ref: '#/components/responses/error'
5XX:
$ref: '#/components/responses/error'
x-ms-docs-operation-type: operation
delete:
tags:
- security.attackSimulationRoot
summary: Microsoft Graph Delete navigation property attackSimulation for security
operationId: security.DeleteAttackSimulation
parameters:
- name: If-Match
in: header
description: ETag
schema:
type: string
responses:
'204':
description: Success
4XX:
$ref: '#/components/responses/error'
5XX:
$ref: '#/components/responses/error'
x-ms-docs-operation-type: operation
/security/attackSimulation/endUserNotifications:
description: >-
Provides operations to manage the endUserNotifications property of the
microsoft.graph.attackSimulationRoot entity.
get:
tags:
- security.attackSimulationRoot
summary: Microsoft Graph List endUserNotifications
description: Get a list of endUserNotification objects and their properties.
externalDocs:
description: Find more info here
url: >-
https://learn.microsoft.com/graph/api/attacksimulationroot-list-endusernotifications?view=graph-rest-1.0
operationId: security.attackSimulation.ListEndUserNotifications
parameters:
- $ref: '#/components/parameters/top'
- $ref: '#/components/parameters/skip'
- $ref: '#/components/parameters/search'
- $ref: '#/components/parameters/filter'
- $ref: '#/components/parameters/count'
- name: $orderby
in: query
description: Order items by property values
style: form
explode: false
schema:
uniqueItems: true
type: array
items:
type: string
- name: $select
in: query
description: Select properties to be returned
style: form
explode: false
schema:
uniqueItems: true
type: array
items:
type: string
- name: $expand
in: query
description: Expand related entities
style: form
explode: false
schema:
uniqueItems: true
type: array
items:
type: string
responses:
2XX:
$ref: >-
#/components/responses/microsoft.graph.endUserNotificationCollectionResponse
4XX:
$ref: '#/components/responses/error'
5XX:
$ref: '#/components/responses/error'
x-ms-pageable:
nextLinkName: '@odata.nextLink'
operationName: listMore
x-ms-docs-operation-type: operation
post:
tags:
- security.attackSimulationRoot
summary: Microsoft Graph Create new navigation property to endUserNotifications for security
operationId: security.attackSimulation.CreateEndUserNotifications
requestBody:
description: New navigation property
content:
application/json:
schema:
$ref: '#/components/schemas/microsoft.graph.endUserNotification'
required: true
responses:
2XX:
description: Created navigation property.
content:
application/json:
schema:
$ref: '#/components/schemas/microsoft.graph.endUserNotification'
4XX:
$ref: '#/components/responses/error'
5XX:
$ref: '#/components/responses/error'
x-ms-docs-operation-typ
# --- truncated at 32 KB (1097 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/microsoft-graph/refs/heads/main/openapi/security-openapi-original.yml