Initiate agent installation on computers

Open in ChatGPT Open in ChatGPT to ask questions about this page
Open in Claude Open in Claude to ask questions about this page
Copy as MarkdownCopy this page as markdown to use with AI assistants
View as Markdown Open this page as markdown in a new tab

Initiates agent installation on one or more computers that are already in the Scope of Management. Returns categorized lists of computers by OS type and agent availability.

Request URL

https://{serverurl}/dcapi/som/computers/installAgent

Scope

DesktopCentralCloud.SOM.CREATECopied!

Header

Authorization: Zoho-oauthtoken d92d4xxxxxxxxxxxxx15f52

Request Parameters

- Request Headers

Content-TypestringMandatory
application/computerIdsToInstallAgent.v1+jsonapplication/computerIdsToInstallAgent.v1+jsonCopied!
AcceptstringMandatory
application/somComputerInstallStatus.v1+jsonapplication/somComputerInstallStatus.v1+jsonCopied!

- Request Body

application/json
JSON Object
Hide Sub-Attributes
computerIDsarrayOptional

Array of computer resource IDs to perform the operation, get computer IDs from the response of the Computers API, under the resource_id field.

Sample Request

Curl
Java
Python
Deluge
PowerShell
Copied!
curl --request POST \
  --url https://appdomains/dcapi/som/computers/installAgent \
  --header 'Accept: application/somComputerInstallStatus.v1+json' \
  --header 'Authorization: Zoho-oauthtoken  d92d4xxxxxxxxxxxxx15f52' \
  --header 'Content-Type: application/computerIdsToInstallAgent.v1+json' \
  --data '{}'

Sample Request Body

Install agent on multiple computers

Copied!
  {
    "computerIDs": [
      "1001",
      "1002",
      "1003"
    ]
  }
                
Show full

Response Parameters

- HTTP code 202

Response Body - application/json
JSON Object
Hide Sub-Attributes
containsAzureADComputersstring

Number of Azure AD-joined computers included in the installation request

requestedComputersarray

Array of resource IDs originally submitted in the installation request

agentAvailableComputersarray

Array of resource IDs for computers where the agent can be installed (meets prerequisites)

windowsComputersarray

Array of resource IDs for Windows computers eligible for agent installation

wanComputersarray

Array of resource IDs for computers located in WAN/remote branch offices

macComputersarray

Array of resource IDs for macOS computers eligible for agent installation

linuxComputersarray

Array of resource IDs for Linux computers eligible for agent installation

isMacSettingsConfiguredboolean

Indicates whether macOS agent distribution settings have been configured on the server

isLinuxSettingsConfiguredboolean

Indicates whether Linux agent distribution settings have been configured on the server

- HTTP code 400

Response Body - application/json
JSON Object
Hide Sub-Attributes
statusCodestring

HTTP status code (400)

errorCodestring

API-specific error code identifying the validation failure

messagestring

Error message describing the validation failure

- HTTP code 412

Response Body - application/json
JSON Object
Hide Sub-Attributes
statusCodestring

HTTP status code (412)

errorCodestring

Precondition failed error code identifying the business logic violation

messagestring

Error message describing the precondition failed while processing request

Possible Response Codes

202HTTP code
400HTTP code
412HTTP code

Sample Response: HTTP 202

Agent install initiated

Copied!
  {
    "containsAzureADComputers": 0,
    "windowsComputers": [
      "1001"
    ],
    "macComputers": [],
    "agentAvailableComputers": [
      "1001",
      "1002"
    ],
    "isMacSettingsConfigured": true,
    "wanComputers": [
      "1002"
    ],
    "linuxComputers": [],
    "requestedComputers": [
      "1001",
      "1002",
      "1003"
    ],
    "isLinuxSettingsConfigured": false
  }
                
Show full

Sample Response: HTTP 400

Missing or empty computerIDs in request

Copied!
  {
    "errorCode": "20006",
    "message": "Resource IDs are not present in the request",
    "statusCode": 400
  }
                
Show full

Sample Response: HTTP 412

Non-admin user cannot access the requested computers

Copied!
  {
    "errorCode": "20005",
    "message": "Selected computers are not accessible",
    "statusCode": 412
  }
                
Show full

Some computers are not managed by the server

Copied!
  {
    "errorCode": "30007",
    "message": "All resources are not managed computers",
    "statusCode": 412
  }
                
Show full

Linux agent settings not configured

Copied!
  {
    "errorCode": "30010",
    "message": "Linux agent settings are not configured",
    "statusCode": 412
  }
                
Show full

Duration: 1 minute | Threshold: 30 | Lock period: 5 minutes

Duration - Time window for the threshold.
Threshold - Number of API calls allowed within the specified duration.
Lock Period - Wait time before consecutive API requests.