openapi: 3.0.0
info:
  title: Devices
  description: Devices API for ManageEngine ID360
  version: 1.0.0
servers:
  - url: 'https://id360.manageengine.com/api/v1'
    description: 'API Endpoint'
tags:
  - name: device
    description: Devices Endpoints
paths:
  /devices:
    get:
      tags:
        - device
      summary: 'List Devices'
      description: 'The List Devices API can be used to get the list of devices in your account.'
      parameters:
        - $ref: '#/components/parameters/acceptHeader'
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/fields'
        - $ref: '#/components/parameters/filter'
        - $ref: '#/components/parameters/sort'
        - $ref: '#/components/parameters/cursor'
      responses:
        '200':
          description: 'OK'
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/deviceResources'
                  meta:
                    $ref: '#/components/schemas/cursorMeta'
        '401':
          description: 'Unauthorized'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/unauthorized'
        '500':
          description: 'Internal Server Error'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/serverError'
      security:
        - Zoho_Auth:
            - id360.device.READ
            - id360.device.ALL

  /devices/{id}:
    get:
      tags:
        - device
      summary: 'Get Device'
      description: 'The Get Device API can be used to get the details of a specific device in your account.'
      parameters:
        - $ref: '#/components/parameters/acceptHeader'
        - $ref: '#/components/parameters/id'
        - $ref: '#/components/parameters/fields'
      responses:
        '200':
          description: 'OK'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/deviceResource'
        '401':
          description: 'Unauthorized'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/unauthorized'
        '404':
          description: 'Not Found'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/deviceNotFound'
        '500':
          description: 'Internal Server Error'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/serverError'
      security:
        - Zoho_Auth:
            - id360.device.READ
            - id360.device.ALL
    delete:
      tags:
        - device
      summary: 'Delete Device/ Uninstall Device Agent'
      description: >
        This api has 2 behaviors:
        <br>
        <ol>
          <li>If the device is enrolled through ID360, it will delete the device and uninstall the agent.</li>
          <li>If the device is enrolled through Entra/AD, it will only uninstall the agent and not delete the device.</li>
        </ol>
      parameters:
        - $ref: '#/components/parameters/acceptHeader'
        - $ref: '#/components/parameters/id'
      responses:
        '204':
          description: No Content
        '401':
          description: 'Unauthorized'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/unauthorized'
        '403':
          description: 'Forbidden'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/accessDenied'
        '404':
          description: 'Not Found'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/mandatoryFieldNotFound'
        '500':
          description: 'Internal Server Error'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/serverError'
      security:
        - Zoho_Auth:
            - id360.device.DELETE
            - id360.device.WRITE
            - id360.device.ALL

  /devices/{id}/activate:
    post:
      tags:
        - device
      summary: 'Activate Device'
      description: 'The Activate Device API can be used to activate the device allowing users linked through IDP to log in to the device.'
      parameters:
        - $ref: '#/components/parameters/acceptHeader'
        - $ref: '#/components/parameters/id'
      responses:
        '204':
          description: No Content
        '401':
          description: 'Unauthorized'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/unauthorized'
        '404':
          description: 'Not Found'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/deviceNotFound'
        '500':
          description: 'Internal Server Error'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/serverError'
      security:
        - Zoho_Auth:
            - id360.device.WRITE
            - id360.device.ALL

  /devices/{id}/deactivate:
    post:
      tags:
        - device
      summary: 'Deactivate Device'
      description: 'The Deactivate Device API can be used to deactivate the device and users linked through IDP will not be able to access the device.'
      parameters:
        - $ref: '#/components/parameters/acceptHeader'
        - $ref: '#/components/parameters/id'
      responses:
        '204':
          description: No Content
        '401':
          description: 'Unauthorized'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/unauthorized'
        '404':
          description: 'Not Found'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/deviceNotFound'
        '500':
          description: 'Internal Server Error'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/serverError'
      security:
        - Zoho_Auth:
            - id360.device.WRITE
            - id360.device.ALL

  /device/{id}/approve-agent:
    post:
      tags:
        - device
      summary: 'Approve Device Agent'
      description: 'The Approve Device Agent API can be used to approve the IDP agent installed on the given device.'
      parameters:
        - $ref: '#/components/parameters/acceptHeader'
        - $ref: '#/components/parameters/id'
      responses:
        '204':
          description: No Content
        '401':
          description: 'Unauthorized'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/unauthorized'
        '404':
          description: 'Not Found'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/deviceNotFound'
        '500':
          description: 'Internal Server Error'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/serverError'
      security:
        - Zoho_Auth:
            - id360.device.WRITE
            - id360.device.ALL

  /device/{id}/deny-agent:
    post:
      tags:
        - device
      summary: 'Deny Device Agent'
      description: 'The Deny Device Agent API can be used to deny the IDP agent installed on the given device.'
      parameters:
        - $ref: '#/components/parameters/acceptHeader'
        - $ref: '#/components/parameters/id'
      responses:
        '204':
          description: No Content
        '401':
          description: 'Unauthorized'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/unauthorized'
        '404':
          description: 'Not Found'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/deviceNotFound'
        '500':
          description: 'Internal Server Error'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/serverError'
      security:
        - Zoho_Auth:
            - id360.device.WRITE
            - id360.device.ALL

  /device/approve-agent:
    post:
      tags:
        - device
      summary: Bulk Approve Device Agent
      description: Bulk Approve Device Agent API can be used to approve the IDP agents installed on the given devices.
      parameters:
        - $ref: '#/components/parameters/acceptHeader'
        - $ref: '#/components/parameters/ids'
      responses:
        '204':
          description: No Content
        '207':
          description: 'Multi-Status'
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/bulkActionsMultiStatus'
        '401':
          description: 'Unauthorized'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/unauthorized'
        '500':
          description: 'Internal Server Error'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/serverError'
      security:
        - Zoho_Auth:
            - id360.device.WRITE
            - id360.device.ALL

  /device/deny-agent:
    post:
      tags:
        - device
      summary: Bulk Deny Device Agent
      description: Bulk Deny Device Agent API can be used to deny the IDP agents installed on the given devices.
      parameters:
        - $ref: '#/components/parameters/acceptHeader'
        - $ref: '#/components/parameters/ids'
      responses:
        '204':
          description: No Content
        '207':
          description: 'Multi-Status'
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/bulkActionsMultiStatus'
        '401':
          description: 'Unauthorized'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/unauthorized'
        '500':
          description: 'Internal Server Error'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/serverError'
      security:
        - Zoho_Auth:
            - id360.device.WRITE
            - id360.device.ALL

components:
  parameters:
    authorization:
      name: Authorization
      in: header
      schema:
        type: string
      description: 'Authorization OAuth token for the API'
      required: true
      example: 'Zoho-oauthtoken 1000.41d**************125f'
    acceptHeader:
      name: Accept
      in: header
      schema:
        type: string
      description: 'Accept header for the API'
      required: false
      example: 'application/json'
    limit:
      in: query
      name: limit
      schema:
        type: integer
        maximum: 200
        minimum: 1
        default: 200
      description: 'Limit the number of devices to be fetched'
      required: false
      example: 50
    fields:
      in: query
      name: fields
      schema:
        type: string
      description: 'Select the fields to be fetched in the response.'
      required: false
      example: 'id,firstName,email'
    filter:
      in: query
      name: filter
      schema:
        type: string
      description: >
        Filter devices based on a the provided SCIM filter query. Refer to filter section for more details
        <br>
        <strong>eg:</strong> name eq "John" and os_type eq "Windows"
      required: false
      example: name eq "John" and os_type eq "Windows"
    sort:
      in: query
      name: sort
      schema:
        type: string
      description: >
        Sort the devices based on the provided field. The default sort order is ascending. To sort in descending order, prefix the field with a - (hyphen).
        <br>
        <strong>eg:</strong> name,-os_type
      required: false
      example: 'firstName,-lastName'
    from:
      in: query
      name: from
      schema:
        type: integer
        default: 1
      description: >
        Start index for pagination.
      required: false
      example: 1
    cursor:
      in: query
      name: cursor
      schema:
        type: string
      description: 'Cursor for pagination. Use the next_cursor value from the previous response to fetch the next set of results.'
      required: false
      example: '2000000000001'
    id:
      in: path
      name: id
      schema:
        type: string
      description: 'The ID of the device to be fetched or deleted'
      example: '2000000000001'
      required: true
    ids:
      in: query
      name: ids
      schema:
        type: string
      description: >
        Comma-separated list of resource IDs.
        <br>
        <strong>eg:</strong> 2000000000011,2000000000012
      required: true
      example: '2000000000011,2000000000012'
  schemas:
    gendoc-attributes-schema:
      $ref: '#/components/schemas/deviceResource'

    deviceResources:
      type: array
      items:
        $ref: '#/components/schemas/deviceResource'
      example:
        - id: "2000000000001"
          hostname: "DESKTOP-WIN11-001"
          os_type: "Windows"
          os_major_version: "11"
          os_release_name: "22H2"
          os_build_version: "22621.2428"
          serial_number: "FVFH2345ABC123"
          ip_address: "192.168.1.45"
          agent_status: "active"
          agent_version: "1.4"
          join_type: "IDPJoined"
          is_deactivated: false
          device_accounts:
            total_local_accounts: 3
            linked_local_accounts: 1
          date_added: "2024-01-15T09:00:00Z"
          last_contact_time: "2024-07-26T10:30:00Z"
        - id: "2000000000002"
          name: "LAPTOP-MAC-002"
          os_type: "macOS"
          os_major_version: "14"
          os_build_version: "14.1.2 (23B92)"
          serial_number: "C02YX1234GHV"
          ip_address: "192.168.1.46"
          agent_status: "pending"
          agent_version: "1.3"
          join_type: "IDPJoined"
          is_deactivated: false
          device_accounts:
            total_local_accounts: 2
            linked_local_accounts: 1
          date_added: "2024-02-01T14:30:00Z"
          last_contact_time: "2024-07-26T10:25:00Z"
        - id: "2000000000004"
          name: "WORKSTATION-LINUX-004"
          os_type: "Linux"
          os_distribution: "Ubuntu"
          os_major_version: "22.04"
          os_build_version: "5.19.0-76-generic"
          serial_number: "VMware-56 4d 8b 2f"
          ip_address: "192.168.1.48"
          agent_status: "pending"
          agent_version: "1.4"
          join_type: "IDPJoined"
          is_deactivated: false
          device_accounts:
            total_local_accounts: 4
            linked_local_accounts: 0
        - id: "2000000000005"
          name: "LAPTOP-ENTRA-005"
          os_type: "Windows"
          os_major_version: "11"
          os_release_name: "22H2"
          os_build_version: "22621.3007"
          serial_number: "PF3K8MN2"
          ip_address: "192.168.1.49"
          agent_status: "active"
          agent_version: "1.5"
          join_type: "EntraJoined"
          tenant: "contoso.onmicrosoft.com"
          description: "Marketing team laptop with Entra ID integration"
          date_added: "2024-05-12T13:45:00Z"
          last_contact_time: "2024-07-26T11:20:00Z"
        - id: "2000000000006"
          name: "DESKTOP-HYBRID-006"
          os_type: "Windows"
          os_major_version: "10"
          os_release_name: "19H2"
          os_build_version: "18363.2274"
          serial_number: "VMJ8K2L9P4"
          ip_address: "192.168.1.50"
          agent_status: "active"
          agent_version: "1.4"
          join_type: "ADEntraHybridJoined"
          tenant: "corp.contoso.com"
          domain: "contoso.onmicrosoft.com"
          description: "Finance workstation with hybrid domain join"
          last_contact_time: "2024-07-26T08:45:00Z"
    deviceResource:
      type: object
      properties:
        id:
          type: string
          example: '2000000000006'
          description: 'Unique identifier for the device'
        name:
          type: string
          example: 'DESKTOP-HYBRID-006'
          description: 'Name of the device'
        os_type:
          type: string
          example: 'Windows'
          enum:
            - Windows
            - macOS
            - Linux
          description: 'Operating system type of the device'
        os_major_version:
          type: string
          example: '10'
          description: 'Major version of the operating system'
        os_release_name:
          type: string
          example: '19H2'
          description: 'Release name of the operating system'
        os_build_version:
          type: string
          example: '18363.2274'
          description: 'Build version of the operating system'
        serial_number:
          type: string
          example: 'VMJ8K2L9P4'
          description: 'Serial number of the device'
        ip_address:
          type: string
          example: '192.168.1.50'
          description: 'IP address of the device'
        agent_status:
          type: string
          example: 'active'
          enum:
            - active
            - inactive
          description: 'Status of the agent installed on the device'
        agent_version:
          type: string
          example: '1.4'
          description: 'Version of the agent installed on the device'
        is_agent_outdated:
          type: boolean
          example: true
          description: 'Indicates if the agent is outdated'
        agent_installed_time:
          type: string
          format: date-time
          example: '2024-06-01T10:30:00+05:30'
          description: 'Time when the agent was installed on the device'
        join_type:
          type: string
          example: 'ADEntraHybridJoined'
          enum:
            - ADEntraHybridJoined
            - ADJoined
            - EntraJoined
            - ID360Joined
          description: 'Join type of the device in the directory'
        domain:
          type: string
          example: 'corp.contoso.com'
          description: 'Domain of the device'
        tenant:
          type: string
          example: 'contoso.onmicrosoft.com'
          description: 'Tenant of the device'
        dns_hostname:
          type: string
          example: 'desktop-hybrid-006.corp.contoso.com'
          description: 'DNS hostname of the device'
        container:
          type: string
          example: 'CN=Computers,DC=corp,DC=contoso,DC=com'
          description: 'Container in which the device is located'
        managed_by:
          type: string
          example: 'CN=Domain Admins,OU=Groups,DC=corp,DC=contoso,DC=com'
          description: 'Group that manages the device'
        owner:
          type: string
          example: 'Admin wamsubdom'
          description: 'Owner of the device'
        mdm:
          type: string
          example: 'Microsoft Intune'
          description: 'Mobile Device Management (MDM) solution managing the device'
        description:
          type: string
          example: 'Finance workstation with hybrid domain join'
          description: 'Description of the device'
        last_contact_time:
          type: string
          format: date-time
          example: '2024-07-26T08:45:00+05:30'
          description: 'Last time the device contacted the server'

    cursorMeta:
      type: object
      properties:
        cursor:
          type: string
          example: null
          description: 'Current cursor specified in the request'
        next_cursor:
          type: string
          example: null
          description: 'Next cursor to be used in the next request'
        is_last:
          type: boolean
          example: true
          description: 'Is this the last page of the response'
        limit:
          type: integer
          example: 100
          description: 'Number of users requested to be in the response'
        total_no_of_objects:
          type: integer
          example: 2
          description: 'Total number of users'
    meta:
      type: object
      properties:
        start_index:
          type: integer
          description: The starting index of the records in the response.
          example: 1
        limit:
          type: integer
          description: The maximum number of records returned in the response.
          example: 100
        total_no_of_objects:
          type: integer
          description: The total number of records available for the request.
          example: 1
    bulkActionsMultiStatus:
      type: array
      items:
        type: object
        properties:
          resource_id:
            type: string
            description: The ID of the resource for whom the action was performed.
            example: '2000000000001'
          status:
            type: integer
            description: HTTP status code indicating the result of the action.
            example: 204
          error:
            $ref: '#/components/schemas/deviceNotFound'
      example:
        - resource_id: '2000000000001'
          status: 204
        - resource_id: '2000000000002'
          status: 404
          error:
            code: '****'
            title: 'Device Not Found'
            detail: 'No device found with ID 2000000000001.'

    deviceNotFound:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              example: '********'
              description: 'Code representing the error'
            title:
              type: string
              example: 'Device Not Found'
              description: 'Title of the error'
            detail:
              type: string
              example: 'No device found with ID 2000000000001.'
              description: 'Detailed message about the error'
    accessDenied:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              example: '********'
              description: 'Code representing the error'
            title:
              type: string
              example: 'Access Denied'
              description: 'Title of the error'
            detail:
              type: string
              example: 'You do not have permission to do this operation.'
              description: 'Detailed message about the error'
    mandatoryFieldNotFound:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              example: 00000107
              description: 'Code representing the error'
            title:
              type: string
              example: 'Invalid Parameter'
              description: 'Title of the error'
            detail:
              type: string
              example: Value for mandatory field 'email' is not provided
              description: 'Detailed message about the error'
    unauthorized:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              example: '00000101'
              description: 'Code representing the error'
            title:
              type: string
              example: 'Unauthorized'
              description: 'Title of the error'
            detail:
              type: string
              example: 'The OAuth token is invalid.'
              description: 'Detailed message about the error'
    serverError:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              example: '00000000'
              description: 'Code representing the error'
            title:
              type: string
              example: 'Internal Server Error'
              description: 'Title of the error'
            detail:
              type: string
              example: 'An unexpected internal error has occurred on the server. Please try again later.'
              description: 'Detailed message about the error'
  securitySchemes:
    Zoho_Auth:
      type: oauth2
      x-authorization-example: 'Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f'
      flows:
        implicit:
          authorizationUrl: https://accounts.zoho.com/oauth/v2/auth
          scopes:
            id360.device.read: 'Read Device from the account'
            id360.device.write: 'Create/Update/Delete Device in the account'
            id360.device.create: 'Create Device in the account'
            id360.device.delete: 'Delete User from the account'
            id360.device.update: 'Update Device in the account'
            id360.device.all: 'Perfrom all actions on Device'
        authorizationCode:
          authorizationUrl: 'https://accounts.zoho.com/oauth/v2/auth'
          tokenUrl: 'https://accounts.zoho.com/oauth/v2/token'
          scopes:
            id360.device.read: 'Read Device from the account'
            id360.device.write: 'Create/Update/Delete Device in the account'
            id360.device.create: 'Create Device in the account'
            id360.device.delete: 'Delete User from the account'
            id360.device.update: 'Update Device in the account'
            id360.device.all: 'Perfrom all actions on Device'
        clientCredentials:
          tokenUrl: https://accounts.zoho.com/oauth/v2/token
          scopes:
            id360.device.read: 'Read Device from the account'
            id360.device.write: 'Create/Update/Delete Device in the account'
            id360.device.create: 'Create Device in the account'
            id360.device.delete: 'Delete User from the account'
            id360.device.update: 'Update Device in the account'
            id360.device.all: 'Perfrom all actions on Device'
        password:
          tokenUrl: https://accounts.zoho.com/oauth/v2/token
          scopes:
            id360.device.read: 'Read Device from the account'
            id360.device.write: 'Create/Update/Delete Device in the account'
            id360.device.create: 'Create Device in the account'
            id360.device.delete: 'Delete User from the account'
            id360.device.update: 'Update Device in the account'
            id360.device.all: 'Perfrom all actions on Device'