# Initiate agent installation on computers

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.

## Endpoint

`POST /dcapi/som/computers/installAgent`

## Request

### Request URL

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

`{serverurl}`: [OAuth authentication endpoint domain](https://www.manageengine.com/products/desktop-central/help/api/cloud/oauth-authentication-endpoint-domain.html)

### Scope

`DesktopCentralCloud.SOM.CREATE`

### Header

`Authorization: Zoho-oauthtoken d92d4xxxxxxxxxxxxx15f52`

### Request Parameters

#### Request Headers

| Parameter | Type | Required | Value |
|---|---|---|---|
| Content-Type | string | Mandatory | `application/computerIdsToInstallAgent.v1+json` |
| Accept | string | Mandatory | `application/somComputerInstallStatus.v1+json` |

#### Request Body

`application/json`

| Attribute | Type | Required | Description |
|---|---|---|---|
| computerIDs | array | Optional | Array of computer resource IDs to perform the operation. Get computer IDs from the response of the [Computers](https://www.manageengine.com/products/desktop-central/help/api/cloud/computers-getcomputers.html) API, under the `resource_id` field. |

### Sample Request

```curl
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:

```json
{
  "computerIDs": [
    "1001",
    "1002",
    "1003"
  ]
}
```

## Response Parameters

### HTTP Code 202

Response body: `application/json`

| Attribute | Type | Description |
|---|---|---|
| containsAzureADComputers | string | Number of Azure AD-joined computers included in the installation request |
| requestedComputers | array | Array of resource IDs originally submitted in the installation request |
| agentAvailableComputers | array | Array of resource IDs for computers where the agent can be installed (meets prerequisites) |
| windowsComputers | array | Array of resource IDs for Windows computers eligible for agent installation |
| wanComputers | array | Array of resource IDs for computers located in WAN/remote branch offices |
| macComputers | array | Array of resource IDs for macOS computers eligible for agent installation |
| linuxComputers | array | Array of resource IDs for Linux computers eligible for agent installation |
| isMacSettingsConfigured | boolean | Indicates whether macOS agent distribution settings have been configured on the server |
| isLinuxSettingsConfigured | boolean | Indicates whether Linux agent distribution settings have been configured on the server |

### HTTP Code 400

Response body: `application/json`

| Attribute | Type | Description |
|---|---|---|
| statusCode | string | HTTP status code (400) |
| errorCode | string | API-specific error code identifying the validation failure |
| message | string | Error message describing the validation failure |

### HTTP Code 412

Response body: `application/json`

| Attribute | Type | Description |
|---|---|---|
| statusCode | string | HTTP status code (412) |
| errorCode | string | Precondition failed error code identifying the business logic violation |
| message | string | Error message describing the precondition failed while processing request |

### Possible Response Codes

| HTTP Code |
|---|
| 202 |
| 400 |
| 412 |

### Sample Response: HTTP 202

Agent install initiated:

```json
{
  "containsAzureADComputers": 0,
  "windowsComputers": [
    "1001"
  ],
  "macComputers": [],
  "agentAvailableComputers": [
    "1001",
    "1002"
  ],
  "isMacSettingsConfigured": true,
  "wanComputers": [
    "1002"
  ],
  "linuxComputers": [],
  "requestedComputers": [
    "1001",
    "1002",
    "1003"
  ],
  "isLinuxSettingsConfigured": false
}
```

### Sample Response: HTTP 400

Missing or empty `computerIDs` in request:

```json
{
  "errorCode": "20006",
  "message": "Resource IDs are not present in the request",
  "statusCode": 400
}
```

### Sample Response: HTTP 412

Non-admin user cannot access the requested computers:

```json
{
  "errorCode": "20005",
  "message": "Selected computers are not accessible",
  "statusCode": 412
}
```

Some computers are not managed by the server:

```json
{
  "errorCode": "30007",
  "message": "All resources are not managed computers",
  "statusCode": 412
}
```

Linux agent settings not configured:

```json
{
  "errorCode": "30010",
  "message": "Linux agent settings are not configured",
  "statusCode": 412
}
```

## API Rate Limit

**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.