# Agents API

**Base URL**: https://dev-cloud.acronis.com/api/agent_manager/v2

## Endpoints

### GET /agents

Fetches all registered agents seen from specified tenant.

Result includes all agents registered in this tenant and in all its child tenants that don't
block parent access using visibility barrier.

#### Security

The endpoint supports the following authorization methods: `OAuth 2.0`

For OAuth2 authorization method, one of the following scopes is required by the endpoint:

* `urn:acronis.com::agent_manager::agent_viewer`
* `urn:acronis.com::agent_manager::admin`

#### Request parameters

##### Query parameters

| Name | Description |
|------|-------------|
| `after` | (Optional) Cursor that designates the last element of a previously returned registered agent subset<br>(page). If this parameter is provided, the next agent page will be returned in the response<br>(according to ordering requirements that were specified in the first request).<br>This parameter is mutually exclusive with all other but limit query parameters. <br>Client must treat it as opaque string.<br><br>**Type**: String |
| `before` | (Optional) Cursor that designates the first element of a previously returned registered agent subset<br>(page). If this parameter is provided, the previous agent page will be returned in the response<br>(according to ordering requirements that were specified in the first request).<br>This parameter is mutually exclusive with all other but limit query parameters. <br>Client must treat it as opaque string.<br><br>**Type**: String |
| `hostname` | (Optional) Either a full name or a name segment (name mask) of a host where registered agent<br>is installed. If this parameter is provided, only agents which host names match the parameter<br>value are returned. Name mask is specified using one of match-like functions:<br>- `hlike` - host name starts with specified string.<br>- `like` - host name contains specified string in any position.<br>- `tlike` - host name ends with specified string.<br><br>**Type**: String |
| `limit` | (Optional) Maximum number of registered agents to return in the response. If this parameter is not provided or<br>set to zero, there is no limit on number of returned agents.<br><br>**Type**: Integer |
| `online` | (Optional) Flag that filters returned registered agents by their current responsiveness.<br>If true, only responsive agents will be returned. If false, only irresponsive agents will be returned.<br><br>**Type**: Boolean |
| `order` | (Optional) Ordering requirements on returned sequence of registered agents. They are specified as<br>a comma-separated list of order specifications for agent attributes. Each attribute order<br>specification is either asc (non-descending order) or desc (non-ascending order) function<br>applied to an attribute name.<br>Currently ordering by the following attributes is supported:<br>- `hostname` - agents with same host names are further ordered in non-descending order by<br>their agent identifiers<br><br>**Type**: String |
| `os_family` | (Optional) Parameter that filters registered agents by OS family name they were built for. OS family name is case-insensitive.<br><br>**Type**: String<br>**Allowed values**:<br>- `UNKNOWN`<br>- `WINDOWS`<br>- `LINUX`<br>- `MACOSX`<br>- `SOLARIS` |
| `tenant_id` | (Optional) Identifier of a tenant subtree root. Only agents that belong to tenants of this subtree<br>are returned. If this parameter is missing, value from `X-Apigw-Tenant-Id` header is used.<br>If this header is also missing, tenant identifiers from relevant elements of scope<br>collection of access token are used.<br><br>**Type**: String |
| `unit` | (Optional) Name of registered agent unit. If this parameter is provided, only agents that have at<br>least one of specified units are returned.<br><br>**Type**: String |
| `up_to_date` | (Optional) Flag specifying whether agents with current or outdated software should only be returned.<br><br>**Type**: Boolean |


#### Responses

| Code | Description |
|------|-------------|
| `200` | Collection of registered agents was successfully retrieved. |
| `400` | Request is malformed. |
| `401` | User authorization failed. There are many reasons for the error. |
| `403` | Access was denied for roles a user plays in Platform. |
| `500` | Service encountered an unexpected condition that prevented it from fulfilling the request. |


### DELETE /agents

Cancels registration of the agents with Platform and deletes their service accounts.

#### Security

The endpoint supports the following authorization methods: `OAuth 2.0`

For OAuth2 authorization method, one of the following scopes is required by the endpoint:

* `urn:acronis.com::agent_manager::agent_unregistrar`
* `urn:acronis.com::agent_manager::admin`

#### Request parameters

##### Query parameters

| Name | Description |
|------|-------------|
| `id` | (Required) Identifier of agent to be deleted.<br><br>**Type**: String |
| `force` | (Optional) Flag specifying whether agent registration should be cancelled even if this is the<br>last agent instance associated with a resource it manages. This flag is only respected<br>for agents that have MMS unit. Other agents are deleted unconditionally.<br><br>**Type**: Boolean<br>**Default**: false |


#### Responses

| Code | Description |
|------|-------------|
| `204` | Registration of specified agents with Platform was either successfully cancelled or didn't exist. |
| `401` | User authorization failed. There are many reasons for the error. |
| `403` | Access was denied for roles a user plays in Platform. |
| `409` | Request violates some invariant. |
| `500` | Service encountered an unexpected condition that prevented it from fulfilling the request. |


### POST /agents/update:force

Launches agent(s) update operation disregarding maintenance window settings, if any.
Note that if an empty agent ID collection is passed with the request, all tenant's agents
become potential subject of update.

Maximum number of agents being updated simultaneously is limited.

#### Security

The endpoint supports the following authorization methods: `OAuth 2.0`

For OAuth2 authorization method, one of the following scopes is required by the endpoint:

* `urn:acronis.com::agent_manager::agent_registrar`
* `urn:acronis.com::agent_manager::admin`

#### Request parameters

##### Request body

**Media type**: application/json

**Schema definition**:

| Name | Description |
|------|-------------|
| `agent_ids` | **Type**: Array of String<br>**Array type description:**<br>**Type**: String |

**Example**:

```json
{
  "agent_ids": [
    ""
  ]
}
```

#### Responses

| Code | Description |
|------|-------------|
| `202` | Agent(s) update request was accepted. |
| `401` | User authorization failed. There are many reasons for the error. |
| `403` | Access was denied for roles a user plays in Platform. |
| `500` | Service encountered an unexpected condition that prevented it from fulfilling the request. |
| `400` | Request is malformed. |


### GET /agents/{agent_id}

Fetches the specific agent.

#### Security

The endpoint supports the following authorization methods: `OAuth 2.0`

For OAuth2 authorization method, one of the following scopes is required by the endpoint:

* `urn:acronis.com::agent_manager::agent_viewer`
* `urn:acronis.com::agent_manager::admin`

#### Request parameters


#### Responses

| Code | Description |
|------|-------------|
| `200` | Agent description was successfully retrieved. |
| `401` | User authorization failed. There are many reasons for the error. |
| `403` | Access was denied for roles a user plays in Platform. |
| `500` | Service encountered an unexpected condition that prevented it from fulfilling the request. |
| `404` | The requested entity cannot be found. |


### DELETE /agents/{agent_id}

Cancels the agent registration with Platform and deletes agent service account.

#### Security

The endpoint supports the following authorization methods: `OAuth 2.0`

For OAuth2 authorization method, one of the following scopes is required by the endpoint:

* `urn:acronis.com::agent_manager::agent_unregistrar`
* `urn:acronis.com::agent_manager::admin`

#### Request parameters

##### Query parameters

| Name | Description |
|------|-------------|
| `force` | (Optional) Flag specifying whether agent registration should be cancelled even if<br>this is the last agent instance associated with a resource it manages.<br>This flag is only respected for an agent that has MMS unit. Any other agent is deleted unconditionally.<br><br>**Type**: Boolean<br>**Default**: false |


#### Responses

| Code | Description |
|------|-------------|
| `204` | Registration of specified agent with Platform was either successfully cancelled or didn't exist. |
| `401` | User authorization failed. There are many reasons for the error. |
| `403` | Access was denied for roles a user plays in Platform. |
| `409` | Request violates some invariant. |
| `500` | Service encountered an unexpected condition that prevented it from fulfilling the request. |


### GET /agent_update_references

Fetches reference to agent update package that matches specified update channel, OS family,
OS architecture and white-labeled flag attributes.

#### Security

The endpoint supports the following authorization methods: `OAuth 2.0`

For OAuth2 authorization method, one of the following scopes is required by the endpoint:

* `urn:acronis.com::agent_manager::agent_update_reference_viewer`
* `urn:acronis.com::agent_manager::admin`

#### Request parameters

##### Query parameters

| Name | Description |
|------|-------------|
| `update_channel` | (Required) Update channel the agent update belongs to.<br><br>**Type**: String<br>**Allowed values**:<br>- `CURRENT`<br>- `STABLE` |
| `os_family` | (Required) Name of operating system family the update was built for.<br><br>**Type**: String<br>**Allowed values**:<br>- `WINDOWS`<br>- `LINUX`<br>- `MACOSX`<br>- `SOLARIS` |
| `os_arch` | (Required) CPU architecture of operating system the update was built for.<br><br>**Type**: String<br>**Allowed values**:<br>- `X86`<br>- `X64`<br>- `ARM`<br>- `ARM64` |
| `white_labeled` | (Optional) Flag specifying whether information about the update package that installs an agent that does not contain references to Acronis as its manufacturer ought to be returned.<br><br>**Type**: Boolean<br>**Default**: false |


#### Responses

| Code | Description |
|------|-------------|
| `200` | Agent update reference was successfully fetched. |
| `400` | Request is malformed. |
| `401` | User authorization failed. There are many reasons for the error. |
| `403` | Access was denied for roles a user plays in Platform. |
| `500` | Service encountered an unexpected condition that prevented it from fulfilling the request. |
| `404` | The requested entity cannot be found. |


### PUT /agent_update_settings

Stores new or updates existing agent-specific or/and master agent update settings. The agent must be
registered to have its specific settings stored.

Each settings object is considered to be agent-specific if it has agent ID field. Otherwise, it is treated
as master settings. The collection must contain single item for each agent or/and tenant.

#### Security

The endpoint supports the following authorization methods: `OAuth 2.0`

For OAuth2 authorization method, one of the following scopes is required by the endpoint:

* `urn:acronis.com::agent_manager::agent_update_settings_modifier`
* `urn:acronis.com::agent_manager::admin`

#### Request parameters

##### Request body

**Media type**: application/json

**Schema definition**:

| Name | Description |
|------|-------------|
| `items` | Collection of unattended agent update settings to be stored by Agent Manager.<br><br>**Type**: Array of Object<br>**Array type description:**<br>Unattended agent update settings to be stored by Agent Manager. The settings can be assigned either to a particular agent instance or to a tenant. In the latter case they are called master settings and apply to every agent that belongs to the tenant and does not have its own settings assigned. Master settings also recursively apply to tenants down tenant hierarchy until a tenant with its own master settings or visibility barrier set is encountered.<br><br>**Type**: Object |

**Example**:

```json
{
  "items": [
    {
      "agent_id": "836fe933-d232-4ed1-b3be-2218f3bbf134",
      "update_channel": "CURRENT",
      "automatic": true,
      "maintenance_window": {
        "time_from": "22:15:00",
        "time_to": "05:00:00",
        "days_of_week": [
          "SATURDAY",
          "FRIDAY"
        ]
      }
    }
  ]
}
```

#### Responses

| Code | Description |
|------|-------------|
| `204` | Unattended agent update settings were successfully stored. |
| `400` | Request is malformed. |
| `401` | User authorization failed. There are many reasons for the error. |
| `403` | Access was denied for roles a user plays in Platform. |
| `500` | Service encountered an unexpected condition that prevented it from fulfilling the request. |


### DELETE /agent_update_settings

Deletes collection of existing agent-specific or master unattended agent update settings.

#### Security

The endpoint supports the following authorization methods: `OAuth 2.0`

For OAuth2 authorization method, one of the following scopes is required by the endpoint:

* `urn:acronis.com::agent_manager::agent_update_settings_modifier`
* `urn:acronis.com::agent_manager::admin`

#### Request parameters

##### Query parameters

| Name | Description |
|------|-------------|
| `id` | (Required) Identifier of agent or tenant which unattended agent update settings to be deleted.<br><br>**Type**: String |
| `master` | (Optional) Boolean flag specifying whether master unattended agent update settings are to be deleted. If the value is true then `id` query parameter is interpreted as ID of tenant the settings belong to. Otherwise, the `id` is interpreted as agent ID.<br><br>**Type**: Boolean<br>**Default**: false |


#### Responses

| Code | Description |
|------|-------------|
| `204` | Specified agent-specific or master unattended agent update settings were successfully deleted, did not exist or the caller does not have access to them. |
| `400` | Request is malformed. |
| `401` | User authorization failed. There are many reasons for the error. |
| `403` | Access was denied for roles a user plays in Platform. |
| `500` | Service encountered an unexpected condition that prevented it from fulfilling the request. |


### GET /agent_update_settings/{id}

Fetches agent-specific or master unattended agent update settings.

If agent-specific settings are requested and the caller has access to tenant that the agent belongs to
according to usual tenant accessibility rules, Agent Manager checks if settings stored specifically for
this agent exist. If they do, they are returned. Otherwise, Agent Manager returns settings it would
return in response to request for master settings of agent's tenant, with the only difference being that
if the master settings are found, they have agent identifier of the agent and do not have tenant
identifier on output.

If master settings of a tenant are requested, Agent Manager behaves differently depending on whether the
caller has access to specified tenant according to usual tenant accessibility rules. If access is
granted but tenant-specific settings are absent, Agent Manager searches for their substitute among
tenants up tenant hierarchy along locator of specified tenant. This locator omits all tenants between
the hierarchy root (as it is seen to Agent Manager) and a tenant with visibility barrier set nearest to
specified tenant. This way the caller may retrieve master settings from a tenant beyond its usual
access scope.

If specified tenant is inaccessible to the caller, search for a substitute is not performed.
Settings of the tenant are only returned to the caller if there is a tenant from caller's access scope
they would be returned for.

If a substitute for master settings is found, it has tenant identifier of the specified tenant on output.

#### Security

The endpoint supports the following authorization methods: `OAuth 2.0`

For OAuth2 authorization method, one of the following scopes is required by the endpoint:

* `urn:acronis.com::agent_manager::agent_update_settings_viewer`
* `urn:acronis.com::agent_manager::admin`

#### Request parameters

##### Query parameters

| Name | Description |
|------|-------------|
| `master` | (Optional) Boolean flag specifying whether master unattended agent update settings should be returned. If the value is true then `{id}` is interpreted as the ID of tenant the settings belong to. Otherwise, the `{id}` is interpreted as the agent ID.<br><br>**Type**: Boolean<br>**Default**: false |


#### Responses

| Code | Description |
|------|-------------|
| `200` | Unattended agent update settings were successfully retrieved. |
| `400` | Request is malformed. |
| `401` | User authorization failed. There are many reasons for the error. |
| `403` | Access was denied for roles a user plays in Platform. |
| `404` | The requested entity cannot be found. |
| `500` | Service encountered an unexpected condition that prevented it from fulfilling the request. |


### DELETE /agent_update_settings/{id}

Deletes existing agent-specific or master unattended agent update settings.

#### Security

The endpoint supports the following authorization methods: `OAuth 2.0`

For OAuth2 authorization method, one of the following scopes is required by the endpoint:

* `urn:acronis.com::agent_manager::agent_update_settings_modifier`
* `urn:acronis.com::agent_manager::admin`

#### Request parameters

##### Query parameters

| Name | Description |
|------|-------------|
| `master` | (Optional) Boolean flag specifying whether master unattended agent update settings are to be deleted. If the value is true then `{id}` is interpreted as the ID of tenant the settings belong to. Otherwise, the `{id}` is interpreted as the agent ID.<br><br>**Type**: Boolean<br>**Default**: false |


#### Responses

| Code | Description |
|------|-------------|
| `204` | Specified agent-specific or master unattended agent update settings were successfully deleted, did not exist or the caller does not have access to them. |
| `400` | Request is malformed. |
| `401` | User authorization failed. There are many reasons for the error. |
| `403` | Access was denied for roles a user plays in Platform. |
| `500` | Service encountered an unexpected condition that prevented it from fulfilling the request. |


### GET /hardware_nodes

Fetches all hardware nodes visible by the specified tenant.

Result includes all nodes registered in this tenant and in all its child tenants that don't
block parent access using visibility barrier.

#### Security

The endpoint supports the following authorization methods: `OAuth 2.0`

For OAuth2 authorization method, one of the following scopes is required by the endpoint:

* `urn:acronis.com::agent_manager::agent_viewer`
* `urn:acronis.com::agent_manager::admin`

#### Request parameters


#### Responses

| Code | Description |
|------|-------------|
| `200` | Hardware node list was successfully retrieved. |
| `401` | User authorization failed. There are many reasons for the error. |
| `403` | Access was denied for roles a user plays in Platform. |
| `500` | Service encountered an unexpected condition that prevented it from fulfilling the request. |


### GET /hardware_nodes/{node_id}

Fetches the specific hardware node.

#### Security

The endpoint supports the following authorization methods: `OAuth 2.0`

For OAuth2 authorization method, one of the following scopes is required by the endpoint:

* `urn:acronis.com::agent_manager::agent_viewer`
* `urn:acronis.com::agent_manager::admin`

#### Request parameters


#### Responses

| Code | Description |
|------|-------------|
| `200` | Hardware node description was successfully retrieved. |
| `401` | User authorization failed. There are many reasons for the error. |
| `403` | Access was denied for roles a user plays in Platform. |
| `500` | Service encountered an unexpected condition that prevented it from fulfilling the request. |
| `404` | The requested entity cannot be found. |