Microsoft Endpoint Configuration Management Devices API

openapi: 3.2.0
info:
  title: Microsoft Endpoint Configuration Management Devices API
  version: 1.0.0
  license:
    name: Microsoft API License
    url: https://learn.microsoft.com/en-us/legal/microsoft-apis/terms-of-use
  description: 'Operations tagged Devices across 3 of this provider''s published API definitions: microsoft-endpoint-configuration-management-configmgr-rest-api-openapi.yml, microsoft-endpoint-configuration-management-intune-data-warehouse-api-openapi.yml, microsoft-endpoint-configuration-management-intune-graph-api-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://{siteserver}/AdminService
  description: Configuration Manager AdminService endpoint
  variables:
    siteserver:
      default: smsproviderfqdn
      description: Fully qualified domain name of the SMS Provider server hosting the administration service.
- url: https://fef.{location}.manage.microsoft.com/ReportingService/DataWarehouseFEService
  description: Intune Data Warehouse endpoint
  variables:
    location:
      default: msua06
      description: Location identifier found in the Data Warehouse API blade in the Microsoft Intune admin center.
- url: https://graph.microsoft.com/v1.0
  description: Microsoft Graph v1.0 production endpoint
- url: https://graph.microsoft.com/beta
  description: Microsoft Graph beta endpoint
tags:
- name: Devices
  description: Query and manage device resources.
paths:
  /wmi/SMS_Device:
    get:
      operationId: listDevicesWmi
      summary: Microsoft Endpoint Configuration Management List devices via WMI route
      description: Retrieve a collection of devices managed by Configuration Manager using the WMI route. Supports OData query options for filtering and selecting.
      tags:
      - Devices
      parameters:
      - $ref: '#/components/parameters/top'
      - $ref: '#/components/parameters/filter'
      - $ref: '#/components/parameters/select'
      - $ref: '#/components/parameters/orderby'
      responses:
        '200':
          description: Successful response returning a collection of devices.
          content:
            application/json:
              schema:
                type: object
                properties:
                  '@odata.context':
                    type: string
                  value:
                    type: array
                    items:
                      $ref: '#/components/schemas/SMS_Device'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
      security:
      - windowsAuth: []
      - oauth2: []
    servers:
    - url: https://{siteserver}/AdminService
      description: Configuration Manager AdminService endpoint
      variables:
        siteserver:
          default: smsproviderfqdn
          description: Fully qualified domain name of the SMS Provider server hosting the administration service.
  /wmi/SMS_R_System:
    get:
      operationId: listSystems
      summary: Microsoft Endpoint Configuration Management List systems
      description: Retrieve all discovered system resources, representing computers and devices discovered by Configuration Manager.
      tags:
      - Devices
      parameters:
      - $ref: '#/components/parameters/top'
      - $ref: '#/components/parameters/filter'
      - $ref: '#/components/parameters/select'
      responses:
        '200':
          description: Successful response returning discovered systems.
          content:
            application/json:
              schema:
                type: object
                properties:
                  value:
                    type: array
                    items:
                      $ref: '#/components/schemas/SMS_R_System'
      security:
      - windowsAuth: []
      - oauth2: []
    servers:
    - url: https://{siteserver}/AdminService
      description: Configuration Manager AdminService endpoint
      variables:
        siteserver:
          default: smsproviderfqdn
          description: Fully qualified domain name of the SMS Provider server hosting the administration service.
  /v1.0/Device:
    get:
      operationId: listDevicesV1
      summary: Microsoft Endpoint Configuration Management List devices (versioned route)
      description: Retrieve devices through the versioned OData v1.0 route which supports new Configuration Manager functionality.
      tags:
      - Devices
      parameters:
      - $ref: '#/components/parameters/top'
      - $ref: '#/components/parameters/filter'
      - $ref: '#/components/parameters/select'
      responses:
        '200':
          description: Successful response returning devices.
          content:
            application/json:
              schema:
                type: object
                properties:
                  value:
                    type: array
                    items:
                      $ref: '#/components/schemas/Device'
      security:
      - windowsAuth: []
      - oauth2: []
    servers:
    - url: https://{siteserver}/AdminService
      description: Configuration Manager AdminService endpoint
      variables:
        siteserver:
          default: smsproviderfqdn
          description: Fully qualified domain name of the SMS Provider server hosting the administration service.
  /v1.0/Device({deviceId}):
    get:
      operationId: getDeviceV1
      summary: Microsoft Endpoint Configuration Management Get a device (versioned route)
      description: Retrieve a specific device by ID via the versioned route.
      tags:
      - Devices
      parameters:
      - name: deviceId
        in: path
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: Successful response returning the device.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Device'
      security:
      - windowsAuth: []
      - oauth2: []
    servers:
    - url: https://{siteserver}/AdminService
      description: Configuration Manager AdminService endpoint
      variables:
        siteserver:
          default: smsproviderfqdn
          description: Fully qualified domain name of the SMS Provider server hosting the administration service.
  /devices:
    get:
      operationId: listDevices
      summary: Microsoft Endpoint Configuration Management List device records
      description: Retrieve historical device records from the Data Warehouse. Returns daily snapshots of device properties including enrollment status, compliance state, and OS information.
      tags:
      - Devices
      parameters:
      - $ref: '#/components/parameters/apiVersion'
      - $ref: '#/components/parameters/top'
      - $ref: '#/components/parameters/skip'
      - $ref: '#/components/parameters/filter_2'
      - $ref: '#/components/parameters/select'
      - $ref: '#/components/parameters/maxhistorydays'
      responses:
        '200':
          description: Successful response returning device records.
          content:
            application/json:
              schema:
                type: object
                properties:
                  value:
                    type: array
                    items:
                      $ref: '#/components/schemas/Device_2'
        '401':
          $ref: '#/components/responses/Unauthorized_2'
        '403':
          $ref: '#/components/responses/Forbidden_2'
      security:
      - oauth2: []
    servers:
    - url: https://fef.{location}.manage.microsoft.com/ReportingService/DataWarehouseFEService
      description: Intune Data Warehouse endpoint
      variables:
        location:
          default: msua06
          description: Location identifier found in the Data Warehouse API blade in the Microsoft Intune admin center.
  /devicePropertyHistories:
    get:
      operationId: listDevicePropertyHistories
      summary: Microsoft Endpoint Configuration Management List device property histories
      description: Retrieve historical device property snapshots. Contains daily snapshots of device-level data for the configured history window.
      tags:
      - Devices
      parameters:
      - $ref: '#/components/parameters/apiVersion'
      - $ref: '#/components/parameters/top'
      - $ref: '#/components/parameters/skip'
      - $ref: '#/components/parameters/filter_2'
      - $ref: '#/components/parameters/select'
      - $ref: '#/components/parameters/maxhistorydays'
      responses:
        '200':
          description: Successful response returning device property history.
          content:
            application/json:
              schema:
                type: object
                properties:
                  value:
                    type: array
                    items:
                      $ref: '#/components/schemas/DevicePropertyHistory'
      security:
      - oauth2: []
    servers:
    - url: https://fef.{location}.manage.microsoft.com/ReportingService/DataWarehouseFEService
      description: Intune Data Warehouse endpoint
      variables:
        location:
          default: msua06
          description: Location identifier found in the Data Warehouse API blade in the Microsoft Intune admin center.
  /deviceManagement/managedDevices:
    get:
      operationId: listManagedDevices
      summary: Microsoft Endpoint Configuration Management List managed devices
      description: List properties and relationships of the managedDevice objects enrolled in Intune.
      tags:
      - Devices
      parameters:
      - $ref: '#/components/parameters/top'
      - $ref: '#/components/parameters/skip'
      - $ref: '#/components/parameters/filter'
      - $ref: '#/components/parameters/select_2'
      - $ref: '#/components/parameters/orderby'
      - $ref: '#/components/parameters/count'
      responses:
        '200':
          description: Successful response returning a collection of managed devices.
          content:
            application/json:
              schema:
                type: object
                properties:
                  '@odata.context':
                    type: string
                  '@odata.count':
                    type: integer
                  '@odata.nextLink':
                    type: string
                  value:
                    type: array
                    items:
                      $ref: '#/components/schemas/ManagedDevice'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden_3'
      security:
      - oauth2: []
    post:
      operationId: createManagedDevice
      summary: Microsoft Endpoint Configuration Management Create managed device
      description: Create a new managedDevice object.
      tags:
      - Devices
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ManagedDevice'
      responses:
        '201':
          description: Successfully created managed device.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ManagedDevice'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
      security:
      - oauth2: []
    servers:
    - url: https://graph.microsoft.com/v1.0
      description: Microsoft Graph v1.0 production endpoint
    - url: https://graph.microsoft.com/beta
      description: Microsoft Graph beta endpoint
  /deviceManagement/managedDevices/{managedDeviceId}:
    get:
      operationId: getManagedDevice
      summary: Microsoft Endpoint Configuration Management Get managed device
      description: Read properties and relationships of a managedDevice object.
      tags:
      - Devices
      parameters:
      - name: managedDeviceId
        in: path
        required: true
        description: The unique identifier of the managed device.
        schema:
          type: string
      - $ref: '#/components/parameters/select_2'
      responses:
        '200':
          description: Successful response returning the managed device.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ManagedDevice'
        '404':
          $ref: '#/components/responses/NotFound'
      security:
      - oauth2: []
    patch:
      operationId: updateManagedDevice
      summary: Microsoft Endpoint Configuration Management Update managed device
      description: Update the properties of a managedDevice object.
      tags:
      - Devices
      parameters:
      - name: managedDeviceId
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ManagedDevice'
      responses:
        '200':
          description: Successfully updated managed device.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ManagedDevice'
      security:
      - oauth2: []
    delete:
      operationId: deleteManagedDevice
      summary: Microsoft Endpoint Configuration Management Delete managed device
      description: Deletes a managedDevice.
      tags:
      - Devices
      parameters:
      - name: managedDeviceId
        in: path
        required: true
        schema:
          type: string
      responses:
        '204':
          description: Successfully deleted.
        '404':
          $ref: '#/components/responses/NotFound'
      security:
      - oauth2: []
    servers:
    - url: https://graph.microsoft.com/v1.0
      description: Microsoft Graph v1.0 production endpoint
    - url: https://graph.microsoft.com/beta
      description: Microsoft Graph beta endpoint
  /users/{userId}/ownedDevices:
    get:
      operationId: listUserOwnedDevices
      summary: Microsoft Endpoint Configuration Management List user owned devices
      description: Get the list of devices registered to a user from Azure Active Directory.
      tags:
      - Devices
      parameters:
      - name: userId
        in: path
        required: true
        schema:
          type: string
      - $ref: '#/components/parameters/top'
      - $ref: '#/components/parameters/select_2'
      responses:
        '200':
          description: Successful response returning user devices.
          content:
            application/json:
              schema:
                type: object
                properties:
                  value:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                        deviceId:
                          type: string
                        displayName:
                          type: string
                        operatingSystem:
                          type: string
                        operatingSystemVersion:
                          type: string
      security:
      - oauth2: []
    servers:
    - url: https://graph.microsoft.com/v1.0
      description: Microsoft Graph v1.0 production endpoint
    - url: https://graph.microsoft.com/beta
      description: Microsoft Graph beta endpoint
components:
  schemas:
    Device:
      type: object
      description: Device entity available through the versioned v1.0 OData route of the AdminService.
      properties:
        MachineId:
          type: integer
          description: Unique machine identifier.
        Name:
          type: string
          description: Device name.
        Domain:
          type: string
          description: Domain.
        IsActive:
          type: boolean
          description: Whether the device is active.
        LastActiveTime:
          type: string
          format: date-time
          description: Last active time.
        DeviceOS:
          type: string
          description: Operating system.
        Status:
          type: string
          description: Device status.
        SiteCode:
          type: string
          description: Associated site code.
    SMS_R_System:
      type: object
      description: Represents a discovered system resource (computer or device) in Configuration Manager.
      properties:
        ResourceID:
          type: integer
          description: Unique resource identifier.
        Name:
          type: string
          description: Computer name.
        SMSUniqueIdentifier:
          type: string
          description: SMS unique identifier.
        ResourceDomainORWorkgroup:
          type: string
          description: Domain or workgroup.
        Client:
          type: integer
          description: Whether the Configuration Manager client is installed (1=yes).
        Active:
          type: integer
          description: Whether the resource is active.
        IPAddresses:
          type: array
          items:
            type: string
          description: IP addresses of the system.
        MACAddresses:
          type: array
          items:
            type: string
          description: MAC addresses of the system.
        OperatingSystemNameandVersion:
          type: string
          description: Full operating system name and version string.
        LastLogonUserName:
          type: string
          description: Last logged on user name.
        LastLogonTimestamp:
          type: string
          format: date-time
          description: Last logon timestamp.
    ODataError:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
            message:
              type: string
    SMS_Device:
      type: object
      description: Represents a device discovered and managed by Configuration Manager via the WMI route.
      properties:
        DeviceID:
          type: integer
          description: Unique device identifier.
        Name:
          type: string
          description: Device name.
        Domain:
          type: string
          description: Domain the device belongs to.
        SMSID:
          type: string
          description: SMS unique identifier.
        IsActive:
          type: boolean
          description: Whether the device is currently active.
        DeviceOS:
          type: string
          description: Operating system of the device.
        DeviceOSVersion:
          type: string
          description: Operating system version.
        DeviceType:
          type: integer
          description: Type of device (1=Desktop, 2=Laptop, etc.).
        IsBlocked:
          type: boolean
          description: Whether the device is blocked.
        LastActiveTime:
          type: string
          format: date-time
          description: Last time the device was active.
    Device_2:
      type: object
      description: Device entity representing a snapshot of device properties in the Data Warehouse.
      properties:
        deviceKey:
          type: integer
          description: Unique identifier of the device in the Data Warehouse.
        deviceId:
          type: string
          description: Unique identifier of the device.
        deviceName:
          type: string
          description: Name of the device.
        deviceType:
          type: string
          description: Type of device.
        operatingSystem:
          type: string
          description: Operating system of the device.
        osVersion:
          type: string
          description: Operating system version.
        ownerType:
          type: string
          description: Type of owner (company, personal, unknown).
        enrolledDateTime:
          type: string
          format: date-time
          description: Date and time the device was enrolled.
        lastSyncDateTime:
          type: string
          format: date-time
          description: Last time the device synced with Intune.
        managementAgent:
          type: string
          description: Management agent type.
        managementState:
          type: string
          description: Management state of the device.
        referenceId:
          type: string
          description: Reference identifier for the device in Azure AD.
        manufacturer:
          type: string
          description: Manufacturer of the device.
        model:
          type: string
          description: Model of the device.
        serialNumber:
          type: string
          description: Serial number of the device.
        isSupervised:
          type: boolean
          description: Whether the device is supervised.
        isEncrypted:
          type: boolean
          description: Whether the device is encrypted.
        dateKey:
          type: integer
          description: Date key reference for the snapshot.
        complianceState:
          type: string
          description: Compliance state of the device.
    DevicePropertyHistory:
      type: object
      description: Historical snapshot of device properties taken daily.
      properties:
        devicePropertyHistoryKey:
          type: integer
          description: Unique key for the history record.
        deviceKey:
          type: integer
          description: Reference to the device.
        dateKey:
          type: integer
          description: Date key for this snapshot.
        deviceName:
          type: string
          description: Device name at the time of snapshot.
        deviceRegistrationStateKey:
          type: integer
          description: Device registration state key.
        complianceStateKey:
          type: integer
          description: Compliance state key.
        osVersion:
          type: string
          description: OS version at the time of snapshot.
        storageTotal:
          type: integer
          format: int64
          description: Total storage in bytes.
        storageFree:
          type: integer
          format: int64
          description: Free storage in bytes.
    ODataError_2:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
            message:
              type: string
            innerError:
              type: object
              properties:
                request-id:
                  type: string
                date:
                  type: string
    ManagedDevice:
      type: object
      description: Devices that are managed or pre-enrolled through Intune.
      properties:
        id:
          type: string
          description: Unique identifier for the device.
          readOnly: true
        userId:
          type: string
          description: Unique identifier for the user associated with the device.
          readOnly: true
        deviceName:
          type: string
          description: Name of the device.
          readOnly: true
        managedDeviceOwnerType:
          type: string
          description: Ownership of the device.
          enum:
          - unknown
          - company
          - personal
        enrolledDateTime:
          type: string
          format: date-time
          description: Enrollment time of the device.
          readOnly: true
        lastSyncDateTime:
          type: string
          format: date-time
          description: The date and time that the device last completed a successful sync with Intune.
          readOnly: true
        operatingSystem:
          type: string
          description: Operating system of the device (Windows, iOS, etc.).
          readOnly: true
        complianceState:
          type: string
          description: Compliance state of the device.
          enum:
          - unknown
          - compliant
          - noncompliant
          - conflict
          - error
          - inGracePeriod
          - configManager
        jailBroken:
          type: string
          description: Whether the device is jail broken or rooted.
          readOnly: true
        managementAgent:
          type: string
          description: Management channel of the device.
          enum:
          - eas
          - mdm
          - easMdm
          - intuneClient
          - easIntuneClient
          - configurationManagerClient
          - configurationManagerClientMdm
          - configurationManagerClientMdmEas
          - unknown
          - jamf
          - googleCloudDevicePolicyController
        osVersion:
          type: string
          description: Operating system version of the device.
          readOnly: true
        easActivated:
          type: boolean
          description: Whether the device is Exchange ActiveSync activated.
          readOnly: true
        easDeviceId:
          type: string
          description: Exchange ActiveSync Id of the device.
          readOnly: true
        azureADRegistered:
          type: boolean
          description: Whether the device is Azure Active Directory registered.
          readOnly: true
        deviceEnrollmentType:
          type: string
          description: Enrollment type of the device.
          enum:
          - unknown
          - userEnrollment
          - deviceEnrollmentManager
          - appleBulkWithUser
          - appleBulkWithoutUser
          - windowsAzureADJoin
          - windowsBulkUserless
          - windowsAutoEnrollment
          - windowsBulkAzureDomainJoin
          - windowsCoManagement
          - windowsAzureADJoinUsingDeviceAuth
          - appleUserEnrollment
          - appleUserEnrollmentWithServiceAccount
          readOnly: true
        emailAddress:
          type: string
          description: Email(s) for the user associated with the device.
          readOnly: true
        azureADDeviceId:
          type: string
          description: The unique identifier for the Azure Active Directory device.
          readOnly: true
        deviceRegistrationState:
          type: string
          description: Device registration state.
          enum:
          - notRegistered
          - registered
          - revoked
          - keyConflict
          - approvalPending
          - certificateReset
          - notRegisteredPendingEnrollment
          - unknown
          readOnly: true
        isSupervised:
          type: boolean
          description: Device supervised status.
          readOnly: true
        isEncrypted:
          type: boolean
          description: Device encryption status.
          readOnly: true
        userPrincipalName:
          type: string
          description: Device user principal name.
          readOnly: true
        model:
          type: string
          description: Model of the device.
          readOnly: true
        manufacturer:
          type: string
          description: Manufacturer of the device.
          readOnly: true
        imei:
          type: string
          description: IMEI.
          readOnly: true
        serialNumber:
          type: string
          description: Serial number of the device.
          readOnly: true
        phoneNumber:
          type: string
          description: Phone number of the device.
          readOnly: true
        androidSecurityPatchLevel:
          type: string
          description: Android security patch level.
          readOnly: true
        userDisplayName:
          type: string
          description: User display name.
          readOnly: true
        wiFiMacAddress:
          type: string
          description: Wi-Fi MAC address.
          readOnly: true
        subscriberCarrier:
          type: string
          description: Subscriber carrier.
          readOnly: true
        meid:
          type: string
          description: MEID.
          readOnly: true
        totalStorageSpaceInBytes:
          type: integer
          format: int64
          description: Total storage in bytes.
          readOnly: true
        freeStorageSpaceInBytes:
          type: integer
          format: int64
          description: Free storage in bytes.
          readOnly: true
        managedDeviceName:
          type: string
          description: Automatically generated name to identify a device. Can be overwritten to a user friendly name.
        partnerReportedThreatState:
          type: string
          description: Threat state of a device when a Mobile Threat Defense partner is in use.
          enum:
          - unknown
          - activated
          - deactivated
          - secured
          - lowSeverity
          - mediumSeverity
          - highSeverity
          - unresponsive
          - compromised
          - misconfigured
          readOnly: true
        physicalMemoryInBytes:
          type: integer
          format: int64
          description: Total memory in bytes.
          readOnly: true
        enrollmentProfileName:
          type: string
          description: Name of the enrollment profile assigned to the device.
          readOnly: true
  parameters:
    select:
      name: $select
      in: query
      description: Comma-separated list of properties to include.
      schema:
        type: string
    top:
      name: $top
      in: query
      description: Number of items to return.
      schema:
        type: integer
    filter:
      name: $filter
      in: query
      description: OData filter expression.
      schema:
        type: string
    orderby:
      name: $orderby
      in: query
      description: Order results by a property.
      schema:
        type: string
    maxhistorydays:
      name: maxhistorydays
      in: query
      description: Maximum number of days of history to retrieve. Only takes effect for collections that include dateKey as part of their key property.
      schema:
        type: integer
        default: 7
    apiVersion:
      name: api-version
      in: query
      required: true
      description: API version. Use 'v1.0' for stable or 'beta' for preview features.
      schema:
        type: string
        enum:
        - v1.0
        - beta
        default: v1.0
    skip:
      name: $skip
      in: query
      description: Number of items to skip.
      schema:
        type: integer
    filter_2:
      name: $filter
      in: query
      description: OData filter expression. Only DateKey or RowLastModifiedDateTimeUTC may be supported for filtering depending on the collection.
      schema:
        type: string
    select_2:
      name: $select
      in: query
      description: Comma-separated list of properties to include in the response.
      schema:
        type: string
    count:
      name: $count
      in: query
      description: Include count of items.
      schema:
        type: boolean
  responses:
    Forbidden:
      description: Forbidden. The user account must be an administrative user in Configuration Manager.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ODataError'
    Unauthorized:
      description: Unauthorized. Authentication is required.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ODataError'
    Forbidden_2:
      description: Forbidden. User must have Intune service administrator role or role-based access to the Intune data warehouse resource.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ODataError'
    Unauthorized_2:
      description: Unauthorized. Microsoft Entra ID authentication with OAuth 2.0 is required.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ODataError'
    NotFound:
      description: Not found. The specified resource does not exist.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ODataError_2'
    Forbidden_3:
      description: Forbidden. Insufficient permissions.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ODataError_2'
    BadRequest:
      description: Bad request. The request body or parameters are invalid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ODataError_2'
  securitySchemes:
    windowsAuth:
      type: http
      scheme: negotiate
      description: Windows Integrated Authentication (Kerberos/NTLM).
    oauth2:
      type: oauth2
      description: OAuth 2.0 via Azure AD for cloud management gateway access.
      flows:
     

# --- truncated at 32 KB (32 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/microsoft-endpoint-configuration-management/refs/heads/main/openapi/microsoft-endpoint-configuration-management-devices-api-openapi.yml