openapi: 3.0.0
info:
  title: Computers API                                      # TITLE OF THE DOCUMENT (REQUIRED)
  description: 'This Computers API provides programmatic access to Active Directory computer accounts. The ADManager Plus API offers endpoints to create, update, list, and disable computers using structured requests with support for filtering, sorting, and pagination. Computer records typically include host names, operating system details, organizational placement, and group memberships, and the API enables these attributes to be managed consistently across environments.'
  contact: {}
  version: 2.0.0
servers:
  -
    url: 'http://admanagerplus:8080/api/v2'                       # PRODUCT URL
    description: 'Product URL'                            # URL DESCRIPTION
tags:
  -
    name: api-for-ad-computers                                      # TAG NAME SHOULD BE SAME AS DEFINED IN APP.YML TAGS & SAME AS YML FILE NAME (REQUIRED)
    description: 'Computers Endpoints'                      # DESCRIPTION ABOUT THE TAG NAME
security:
  - authToken: []
paths:
  /computers:
    get:
      tags:
      - api-for-ad-computers
      summary: List AD Computers
      description: |
        This endpoint retrieves AD computer objects based on filters, sorting, and pagination. It allows you to fetch only the required attributes, making queries efficient and tailored to your reporting needs. It is especially useful for generating inventories, auditing systems, or identifying computers that meet specific conditions.
      operationId: get-api-v2-computers
      parameters:
        - $ref: '#/components/parameters/acceptHeader'
        - $ref: '#/components/parameters/xModule'
        - $ref: '#/components/parameters/date_format'
        - $ref: '#/components/parameters/from'
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/domains'
        - $ref: '#/components/parameters/fields'
        - $ref: '#/components/parameters/filter'
        - $ref: '#/components/parameters/sort'
        - $ref: '#/components/parameters/refresh'
      responses:
        "200":
          description: Successful response with AD computers.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/list_computers_response'
        "400":
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/bad_request_response'
        "401":
          description: UnAuthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/unauthorized_response'
        "500":
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/internal_server_error_response'
      deprecated: false
      security:
        - authToken: 
          - Read computer action, All computer management actions
          - delegated-roles
          - All Computers Report
    post:
      tags:
      - api-for-ad-computers
      summary: Create AD Computers
      description: This endpoint creates new AD computer objects, either individually or in bulk. You can apply a default or custom template to ensure consistency in attributes such as OU placement, or naming conventions. It is typically used when onboarding new machines into the domain or automating bulk computer account creation.
      parameters:
        - $ref: '#/components/parameters/domain'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/create_computers_body'
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/create_computers_response'
        "400":
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/bad_request_response'
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/unauthorized_response'
        "500":
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/internal_server_error_response'
      deprecated: false
      security:
        - authToken: 
          - Create computer action, All computer management actions
          - delegated-roles
          - Create Bulk Computers
    patch:
      tags:
      - api-for-ad-computers
      summary: Update AD Computers
      description: This endpoint updates existing AD computer objects with the specified payload. You can modify core properties like name, description, and OU, or update advanced details such as operating system, account control, or membership. It is commonly used during upgrades, reorganizations, or when reassigning management responsibilities.
      operationId: patch-api-v2-computers
      parameters:
        - $ref: '#/components/parameters/acceptHeader'
        - $ref: '#/components/parameters/xModule'
        - $ref: '#/components/parameters/from'
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/domain'
        - $ref: '#/components/parameters/filter'
        - $ref: '#/components/parameters/sort'
        - $ref: '#/components/parameters/refresh'
      requestBody:
        description: ""
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/update_computers_body'
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/update_computers_response'
        "400":
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/bad_request_response'
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/unauthorized_response'
        "500":
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/internal_server_error_response'
      deprecated: false
      security:
        - authToken: 
          - Modify computer action, All computer management actions
          - delegated-roles
          - Modify Computers using CSV, Bulk Computer Modification
  /computers/disable:
    post:
      tags:
      - api-for-ad-computers
      summary: Disable AD Computers
      description: "This endpoint disables one or more AD computers that match the provided filters. A disabled computer cannot authenticate to the domain but remains in AD for record-keeping and auditing. It is often used to secure decommissioned, inactive, or non-compliant machines in bulk. "
      parameters:
        - $ref: '#/components/parameters/acceptHeader'
        - $ref: '#/components/parameters/xModule'
        - $ref: '#/components/parameters/from'
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/domain'
        - $ref: '#/components/parameters/filter'
        - $ref: '#/components/parameters/sort'
        - $ref: '#/components/parameters/refresh'
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/disable_computers_response'
        "400":
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/bad_request_response'
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/unauthorized_response'
        "500":
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/internal_server_error_response'
      deprecated: false
      security:
        - authToken: 
          - Modify computer action, All computer management actions
          - delegated-roles
          - Enable/Disable Computers
components:
  parameters:
    authorization:
      name: Authorization
      in: header
      schema:
        type: string
      description: 'Authtoken for the API'
      required: true
      example: '41d**************125f'
    acceptHeader:
      name: Accept
      in: header
      schema:
        type: string
      description: 'The response format that the client accepts.'
      required: false
      example: 'application/json'
    contentType:
      name: Content-Type
      in: header
      schema:
        type: string
      description: 'The format of data sent to the server. This value is passed in the Content-Type header of the API request.'
      required: false
      example: 'application/json'
    xModule:
      name: X-Module
      in: header
      schema:
        type: string
      description: 'The response format that the client accepts. This value is passed in the Accept header of the API request.'
      required: false
      example: 'External API'
    date_format :
      name: X-Date-Time-Format
      in: header
      description: "The date-time format to be used for parsing date values returned in the response. If not provided, the default ISO format is used (yyyy-MM-dd'T'HH:mm:ss[.SSS][XXX])."
      required: false
      schema:
        type: string
    from:
      in: query
      name: from
      schema:
        type: integer
        minimum: 1
      description: 'The starting index for pagination. Enables pagination through large result sets.'
      required: false
      example: 1
    limit:
      in: query
      name: limit
      schema:
        type: integer
        maximum: 100
        minimum: 1
      description: 'The maximum number of computers records to return per request.'
      required: false
      example: 50
    domains:
      in: query
      name: domains
      schema:
        type: string
      description: >
        A comma-separated list of domains from which to fetch computers. 
        <br>
        <strong>Example:</strong>  domain1.com,domain2.com
      required: true
      example: domain1.com
    fields:
      in: query
      name: fields
      schema:
        type: string
      description: 'The attributes to be returned in the response.'
      required: false
      example: 'SAM_ACCOUNT_NAME,EMAIL_ADDRESS,MEMBER_OF'
    filter:
      in: query
      name: filter
      schema:
        type: string
      description: >
        A SCIM filter query to refine which objects are returned. See <a href="https://www.manageengine.com/in/products/ad-manager/active-directory-api/v2/filters/#overview">Filter section</a> for details.
        <br>
        <strong>Example:</strong> (SAM_ACCOUNT_NAME eq PC01) and (OPERATING_SYSTEM eq Windows 11)
      required: false
    sort:
      in: query
      name: sort
      schema:
        type: string
      description: >
        This field is used to sort results. The default sort order is ascending. To sort in descending order, prefix the field with a - (hyphen).
        <br>
        <strong>Example:</strong> SAM_ACCOUNT_NAME,-OPERATING_SYSTEM
      required: false
    refresh:
      in: query
      name: refresh
      description: If set to true, triggers a sync before fetching results, ensuring that the data reflects the latest state of AD.
      required: false
      schema:
        type: boolean
    domain:
      in: query
      name: domain
      description: >
        The AD domain where the requested operation is performed.
        <br>
        <strong>Example:</strong> domain1.com
      required: true
      schema:
        type: string
      example: domain1.com
  schemas:
    bad_request_response:
      type: object
      properties:
        code:
          type: string
          description: Error code
          example: "00000100"
        detail:
          type: string
          description: Detailed error message
          example: "Some columns given in fields parameter are invalid"
        title:
          type: string
          description: Short error message
          example: "Bad Request."
    unauthorized_response:
      type: object
      properties:
        code:
          type: string
          description: Error code
          example: "00000101"
        detail:
          type: string
          description: Detailed error message
          example: "The given Authtoken is invalid."
        title:
          type: string
          description: Short error message
          example: "Unauthorized."
    internal_server_error_response:
      type: object
      properties:
        code:
          type: string
          description: Error code
          example: "00000000"
        detail:
          type: string
          description: Detailed error message
          example: "An internal server error occurred."
        title:
          type: string
          description: Short error message
          example: "Internal Server Error."

    list_computers_response: 
      type: object
      properties:
        data:
          type: array
          example:
          - COMPUTER_NAME: "APIComputer1"
            DISTINGUISHED_NAME: "CN=APIComputer1,OU=APIComputers,DC=test,DC=com"
            OU_NAME: "APIComputers"
            VERSION: "-"
            SID_STRING: "S-1-5-21-823222356-1721523957-3165990102-24870"
            OBJECT_GUID: "{BD96FD3L-7010-40CD-8F28-DFFD8F11D227}"
            MANAGER: "Manager 1"
            OPERATING_SYSTEM: "Windows"
            DEPARTMENT: "IT"
            SAM_ACCOUNT_NAME: "APIComputer1$"
          - COMPUTER_NAME: "APIComputer2"
            DISTINGUISHED_NAME: "CN=APIComputer2,OU=APIComputers,DC=test,DC=com"
            OU_NAME: "APIComputers"
            VERSION: "-"
            SID_STRING: "S-1-5-21-823222356-1721523957-3165990102-24871"
            OBJECT_GUID: "{BD96FD3L-7010-40CD-8F28-DFFD8F11D228}"
            MANAGER: "Manager 2"
            OPERATING_SYSTEM: "Windows Server"
            DEPARTMENT: "IT"
          - COMPUTER_NAME: "APIComputer3"
            DISTINGUISHED_NAME: "CN=APIComputer3,OU=APIComputers,DC=test,DC=com"
            OU_NAME: "APIComputers"
            VERSION: "-"
            SID_STRING: "S-1-5-21-823222356-1721523957-3165990102-24872"
            OBJECT_GUID: "{BD96FD3L-7010-40CD-8F28-DFFD8F11D229}"
            MANAGER: "Manager 3"
            OPERATING_SYSTEM: "Linux"
            DEPARTMENT: "IT"
          - COMPUTER_NAME: "APIComputer4"
            DISTINGUISHED_NAME: "CN=APIComputer4,OU=APIComputers,DC=test,DC=com"
            OU_NAME: "APIComputers"
            VERSION: "-"
            SID_STRING: "S-1-5-21-823222356-1721523957-3165990102-24873"
            OBJECT_GUID: "{BD96FD3L-7010-40CD-8F28-DFFD8F11D230}"
            MANAGER: "Manager 4"
            OPERATING_SYSTEM: "macOS"
            DEPARTMENT: "IT"
        meta:
          $ref: '#/components/schemas/meta'
    computers_array:
      type: array
      items:
        example:
          - COMPUTER_NAME: "APIComputer1"
            DISTINGUISHED_NAME: "CN=APIComputer1,OU=APIComputers,DC=test,DC=com"
            OU_NAME: "APIComputers"
            VERSION: "-"
            SID_STRING: "S-1-5-21-823222356-1721523957-3165990102-24870"
            OBJECT_GUID: "{BD96FD3L-7010-40CD-8F28-DFFD8F11D227}"
            MANAGER: "Manager 1"
            OPERATING_SYSTEM: "Windows"
            DEPARTMENT: "IT"
            SAM_ACCOUNT_NAME: "APIComputer1$"
          - COMPUTER_NAME: "APIComputer2"
            DISTINGUISHED_NAME: "CN=APIComputer2,OU=APIComputers,DC=test,DC=com"
            OU_NAME: "APIComputers"
            VERSION: "-"
            SID_STRING: "S-1-5-21-823222356-1721523957-3165990102-24871"
            OBJECT_GUID: "{BD96FD3L-7010-40CD-8F28-DFFD8F11D228}"
            MANAGER: "Manager 2"
            OPERATING_SYSTEM: "Windows Server"
            DEPARTMENT: "IT"
          - COMPUTER_NAME: "APIComputer3"
            DISTINGUISHED_NAME: "CN=APIComputer3,OU=APIComputers,DC=test,DC=com"
            OU_NAME: "APIComputers"
            VERSION: "-"
            SID_STRING: "S-1-5-21-823222356-1721523957-3165990102-24872"
            OBJECT_GUID: "{BD96FD3L-7010-40CD-8F28-DFFD8F11D229}"
            MANAGER: "Manager 3"
            OPERATING_SYSTEM: "Linux"
            DEPARTMENT: "IT"
          - COMPUTER_NAME: "APIComputer4"
            DISTINGUISHED_NAME: "CN=APIComputer4,OU=APIComputers,DC=test,DC=com"
            OU_NAME: "APIComputers"
            VERSION: "-"
            SID_STRING: "S-1-5-21-823222356-1721523957-3165990102-24873"
            OBJECT_GUID: "{BD96FD3L-7010-40CD-8F28-DFFD8F11D230}"
            MANAGER: "Manager 4"
            OPERATING_SYSTEM: "macOS"
            DEPARTMENT: "IT"
    meta:
      type: object
      properties:
        start_index:
          type: integer
          example: 1
        limit:
          type: integer
          example: 4
        total_no_of_objects:
          type: integer
          example: 200
    
    create_computers_response:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/create_computers_data'
          example:
            - object:
                Name: "APIComputer1"
                Manager(AD): "Manager 1"
                Description: "Computer created via API"
              status:
                status_code: 1
                status_message: "Successfully created the computer."
            - object:
                Computer Name: "APIComputer2"
                SAM Account Name: "APIComputer2$"
              status:
                status_code: 0
                status_message: "Value for managedBy attribute could not be found in AD. Value for the managedBy attribute must be specified in DN format or mail or displayName"
        meta:
          $ref: '#/components/schemas/meta'
          example:
            start_index: 1
            limit: 2
            total_no_of_objects: 2
    create_computers_data:
      type: object
      properties:
        object:
          $ref: '#/components/schemas/creation_object_data'
        status:
          $ref: '#/components/schemas/status'
    creation_object_data:
      type: object
      properties:
        Name:
          type: string
        Manager(AD):
          type: string
        Description:
          type: string
        SAM Account Name:
          type: string
        Computer Name:
          type: string
    status:
      type: object
      properties:
        status_code:
          type: integer
        status_message:
          type: string
    create_computers_body:
      type: object
      properties:
        template:
          $ref: '#/components/schemas/creation_template'
          description: >
            The template to be used when creating the computer. If not specified, the default system template is applied.
          example:
            template_name: "Computer Creation Template"
        data:
          type: array
          items:
            type: object
            properties:
              attributes:
                $ref: '#/components/schemas/api_attributes'
                description: >
                  The attributes of the computer object to be created.
          description: >
            The data and attributes used for computer creation.
          example:
            - attributes:
                sAMAccountName: "APIComputer1$"
                name: "APIComputer1"
                OUName: "OU=Computers,DC=test,DC=com"
                description: "Computer created via API"
                memberOf: "Test Group1;Test Group2"
            - attributes:
                sAMAccountName: "APIComputer2$"
                name: "APIComputer2"
                OUName: "OU=Computers,DC=test,DC=com"
                description: "Computer created via API"
                memberOf: "Test Group3;Test Group4"
                managedBy: "Manager2"
                extensionAttribute1: "Test Attribute 2"
    creation_template:
      type: object
      properties:
        template_name:
          type: string
          description: >
            The name of the template used to create the computer.
        template_id:
          type: integer
          description: >
            The ID of the template used to create the computer.
    creation_computer_data:
      type: object
      properties:
        attributes:
          $ref: '#/components/schemas/api_attributes'
          description: >
            Attributes of the Computer to be created.
    api_attributes:
      type: object
      properties:
        name: 
          type: string
          description: "The name of the computer."
        description:
          type: string
          description: "The description of the computer."
        sAMAccountName:
          type: string
          description: "The SAM account name of the computer."
        displayName:
          type: string
          description: "The display name of the computer."
        dNSHostName:
          type: string
          description: "The DNS host name of the computer."
        operatingSystem:
          type: string
          description: "The OS installed on the computer."
        operatingSystemServicePack:
          type: string
          description: "The service pack level of the OS."
        operatingSystemVersion:
          type: string
          description: "The version of the OS."
        userAccountControl:
          type: integer
          description: "The user account control settings for the computer."
        memberOf:
          type: string
          description: "The groups that the computer belongs to"
        managedBy:
          type: string
          description: "The manager responsible for the computer."
        department:
          type: string
          description: "The department associated with the computer."
        OUName:
          type: string
          description: "The OU where the computer resides."
        preventDeletion:
          type: boolean
          description: "Specifies whether the computer object is protected from accidental deletion."
    
    update_computers_body:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/update_computer_data'
          description: >
            Data and attributes to be used for the computer modification.
          example:
            attributes:
              name: "UpdatedComputerName"
              OUName: "OU=UpdatedComputers,DC=test,DC=com"
              description: "Updated description for the computer"
              memberOf: "Updated Group1;Updated Group2"
              managedBy: "Updated Manager"
              extensionAttribute1: "Updated Attribute"
    update_computer_data:
      type: object
      properties:
        attributes:
          $ref: '#/components/schemas/api_attributes'
          description: >
            The attributes of the computer object to be updated.
    
    update_computers_response:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/update_computers_data'
          description: >
            Data and attributes to be used for the computer modification.
          example:
            - object:
                Distinguished Name: "CN=UpdatedComputer1,OU=Computers,DC=test,DC=com"
                Description: "Updated description for the computer"
                Member of: "Updated Group1;Updated Group2"
              status:
                status_code: 1
                status_message: "Successfully updated the computer."
            - object:
                Distinguished Name: "CN=UpdatedComputer2,OU=Computers,DC=test,DC=com"
                Description: "Updated description for the computer"
              status:
                status_code: 0
                status_message: "Value for managedBy attribute could not be found in AD. Value for the managedBy attribute must be specified in DN format or mail or displayName"
        meta:
          $ref: '#/components/schemas/meta'
          example:
            start_index: 1
            limit: 2
            total_no_of_objects: 20
    update_computers_data:
      type: object
      properties:
        object:
          $ref: '#/components/schemas/modification_object_data'
        status:
          $ref: '#/components/schemas/status'
    modification_object_data:
      type: object
      properties:
        Distinguished Name:
          type: string
        Description:
          type: string
        Member of:
          type: string
    
    disable_computers_response:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/disable_computers_data_success'
          example:
            - object:
                Computer Name: "APIC4"
                SAM Account Name: "APIC4$"
                Distinguished Name: "CN=APIC4,OU=Computers,DC=test,DC=com"
                Managed by: "Manager"
                OU Name: "OU=Computers,DC=test,DC=com"
              status:
                status_code: 1
                status_message: "Successfully Disabled."
        meta:
          $ref: '#/components/schemas/meta'
          example:
            start_index: 1
            limit: 1
            total_no_of_objects: 10
    disable_computers_data_success:
      type: object
      properties:
        object:
          $ref: '#/components/schemas/disable_object_data'
        status:
          $ref: '#/components/schemas/status'
    disable_object_data:
      type: object
      properties:
        Computer Name:
          type: string
        SAM Account Name:
          type: string
        Distinguished Name:
          type: string
        Managed by:
          type: string
        OU Name:
          type: string
  securitySchemes:
    authToken:
      type: apiKey
      in: header
      name: Authorization
