Microsoft Endpoint Configuration Management Collections API

openapi: 3.2.0
info:
  title: Microsoft Endpoint Configuration Management Configuration Manager REST API (AdminService) Collections API
  description: REST API for managing Configuration Manager resources including collections, deployments, applications, and device queries. The administration service is based on the OData v4 protocol and supports both WMI and versioned OData routes. Class names are case-sensitive.
  version: 1.0.0
  contact:
    name: Microsoft Configuration Manager Support
    url: https://learn.microsoft.com/en-us/intune/configmgr/develop/adminservice/overview
  license:
    name: Microsoft API License
    url: https://learn.microsoft.com/en-us/legal/microsoft-apis/terms-of-use
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.
security:
- windowsAuth: []
- oauth2: []
tags:
- name: Collections
  description: Manage device and user collections.
paths:
  /wmi/SMS_Collection:
    get:
      operationId: listCollections
      summary: Microsoft Endpoint Configuration Management List collections
      description: Retrieve all device and user collections defined in Configuration Manager.
      tags:
      - Collections
      parameters:
      - $ref: '#/components/parameters/top'
      - $ref: '#/components/parameters/filter'
      - $ref: '#/components/parameters/select'
      - $ref: '#/components/parameters/orderby'
      responses:
        '200':
          description: Successful response returning collections.
          content:
            application/json:
              schema:
                type: object
                properties:
                  value:
                    type: array
                    items:
                      $ref: '#/components/schemas/SMS_Collection'
    post:
      operationId: createCollection
      summary: Microsoft Endpoint Configuration Management Create a collection
      description: Create a new device or user collection.
      tags:
      - Collections
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SMS_Collection'
      responses:
        '201':
          description: Successfully created collection.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SMS_Collection'
  /wmi/SMS_Collection('{collectionId}'):
    get:
      operationId: getCollection
      summary: Microsoft Endpoint Configuration Management Get a collection
      description: Retrieve a specific collection by its ID.
      tags:
      - Collections
      parameters:
      - name: collectionId
        in: path
        required: true
        description: The unique identifier of the collection.
        schema:
          type: string
      responses:
        '200':
          description: Successful response returning the collection.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SMS_Collection'
        '404':
          $ref: '#/components/responses/NotFound'
  /v1.0/Collections:
    get:
      operationId: listCollectionsV1
      summary: Microsoft Endpoint Configuration Management List collections (versioned route)
      description: Retrieve collections through the versioned OData v1.0 route.
      tags:
      - Collections
      parameters:
      - $ref: '#/components/parameters/top'
      - $ref: '#/components/parameters/filter'
      - $ref: '#/components/parameters/select'
      responses:
        '200':
          description: Successful response returning collections.
          content:
            application/json:
              schema:
                type: object
                properties:
                  value:
                    type: array
                    items:
                      $ref: '#/components/schemas/SMS_Collection'
components:
  schemas:
    ODataError:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
            message:
              type: string
    SMS_Collection:
      type: object
      description: Represents a device or user collection in Configuration Manager used for targeting deployments and policies.
      properties:
        CollectionID:
          type: string
          description: Unique collection identifier.
        Name:
          type: string
          description: Collection name.
        Comment:
          type: string
          description: Collection description/comment.
        CollectionType:
          type: integer
          description: Type of collection (1=User, 2=Device).
        MemberCount:
          type: integer
          description: Number of members in the collection.
        LimitToCollectionID:
          type: string
          description: The collection ID that limits membership.
        LimitToCollectionName:
          type: string
          description: Name of the limiting collection.
        LastRefreshTime:
          type: string
          format: date-time
          description: Last time the collection membership was refreshed.
        CurrentStatus:
          type: integer
          description: Current evaluation status of the collection.
  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
  responses:
    NotFound:
      description: Not found. The specified resource does not exist.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ODataError'
  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:
        authorizationCode:
          authorizationUrl: https://login.microsoftonline.com/common/oauth2/v2.0/authorize
          tokenUrl: https://login.microsoftonline.com/common/oauth2/v2.0/token
          scopes: {}