Agents

Agents are installed on distinct physical and online virtual machines and have the ability to independently initiate specific actions. With the Agents functions you can:

  • Delete an agent from a machine
  • Query for information about current agent installations
  • Assign a different policy to an agent

Base URL

        https://<consoleFQDN:port>/st/console/api/v1.0/agents

Supported Requests

Method

URL

Input

Return

DELETE

https://<consoleFQDN:port>/st/console/api/v1.0/agents/{agentId}

Request Body

Success code

GET

https://<consoleFQDN:port>/st/console/api/v1.0/agents

URL Parameters

AgentDetail

https://<consoleFQDN:port>/st/console/api/v1.0/agents/{agentId}

 

AgentDetail

https://<consoleFQDN:port>/st/console/api/v1.0/agents/{agentId}/status

 

AgentStatus

PUT

https://<consoleFQDN:port>/st/console/api/v1.0/agents/{agentId}/policy

Request Body

Success code

Input Models

Name

Type

Description

count

Int32

Provides the number of agents to return. The default is 10 and the maximum value is 1000.

listening

Boolean

Returns agents that are configured as listening agents.

name

String

Returns the agent whose host or DNS name equals this value.

start

Int32

Provides the start index for pagination.

Name

Required?

Type

Default Value

Description

policyId

Yes for PUT

N/A for DELETE

Guid

None

Specifies the ID of the policy you want to reassign to the agent.

checkIn

No

Boolean

True

Specifies if the agent will check in with the console to immediately receive the new policy. If the agent is currently a listening agent, the check-in will occur even if you specify checkin=false.

Example with Sample Response

Find all agent installations

GET Request

https://<consoleFQDN:port>/st/console/api/v1.0/agents

Sample Response

Copy 
{
    "count": 1,
    "links": {
        "next": {
            "href": "https://device-name.example.com:3121/st/console/api/v1.0/agents?start=2"
        }
    },
    "value": [
        {
            "agentId": "D0C5F75A80FFD5DEA9A2073A2202FF890C2B6223",
            "assignedPolicyId": "c09064c8-3825-4bcb-8dae-16c71e6bc986",
            "dnsName": "device-name.example.com",
            "domain": "FAKE",
            "frameworkVersion": "9.5.3677.0",
            "isListening": true,
            "lastCheckIn": "2019-09-25T19:39:57.17",
            "links": {
                "self": {
                    "href": "https://device-name.example.com:3121/st/console/api/v1.0/agents/D0C5F75A80FFD5DEA9A2073A2202FF890C2B6223"
                },
                "status": {
                    "href": "https://device-name.example.com:3121/st/console/api/v1.0/agents/D0C5F75A80FFD5DEA9A2073A2202FF890C2B6223/status"
                },
                "checkin": {
                    "href": "https://device-name.example.com:3121/st/console/api/v1.0/agenttasks/D0C5F75A80FFD5DEA9A2073A2202FF890C2B6223/checkin"
                },
                "tasks": {
                    "href": "https://device-name.example.com:3121/st/console/api/v1.0/agenttasks/D0C5F75A80FFD5DEA9A2073A2202FF890C2B6223/tasks"
                },
                    "queuedTasks": {
                    "href": "https://device-name.example.com:3121/st/console/api/v1.0/agenttasks/D0C5F75A80FFD5DEA9A2073A2202FF890C2B6223/queuedTask"
                }
            },
            "listeningPort": 4155,
            "machineName": "device-name",
            "reportedPolicyId": "c09064c8-3825-4bcb-8dae-16c71e6bc986",
            "status": "Installed"
        }
    ]
}

Other Request Examples

DELETE Request

https://<consoleFQDN:port>/st/console/api/v1.0/agents/0123456789ABCDEF01230123456789ABCDEF0123

GET Request

https://<consoleFQDN:port>/st/console/api/v1.0/agents?Count=5&Listening=true

GET Request

https://<consoleFQDN:port>/st/console/api/v1.0/agents?Name=SampleMachine

GET Request

https://<consoleFQDN:port>/st/console/api/v1.0/agents/0123456789ABCDEF01230123456789ABCDEF0123

GET Request

https://<consoleFQDN:port>/st/console/api/v1.0/agents/0123456789ABCDEF01230123456789ABCDEF0123/status

PUT Request

Copy 
https://<consoleFQDN:port>/st/console/api/v1.0/agents/0123456789ABCDEF01230123456789ABCDEF0123/policy

{
    "policyId": "bb783e46-629e-4689-a3f5-1a1ba17b7ab8"
}

Output Models

Name

Type

Description

agentId

String

The agent ID.

assignedPolicyId

Guid

The unique identifier of the policy that is in effect for this agent.

dnsName

String

The DNS name of the agent machine.

domain

String

The domain of the agent machine.

frameworkVersion

String

The installed agent framework version.

isListening

Boolean

Specifies if the agent is a listening agent.

lastCheckIn

DateTime

The most date and time of the most recent check in.

lastKnownIPAddress

String

The last known IP address of the agent machine.

links

Links

Shows the related URLs for the agent.

listeningPort

Int32

The listening port number.

machineName

String

The agent machine's host name.

reportedPolicyId

Guid

The agent's policy ID.

status

Enum

The current status of the agent. Valid values are:

•None: No assigned agent

•Legacy56Installed: A 5.6 version legacy agent is installed.

•LegacyInstalled: A legacy agent is installed.

•LegacyStopPending: A legacy agent stop operation is pending.

•LegacyInstallPending: A legacy agent install operation is pending.

•LegacyInstallRunning: The legacy agent installation is currently in progress.

•LegacyInstallFailed: A legacy agent installation failed.

•LegacyError: Install error.

•LegacyUninstallPending: An agent removal operation is pending completion.

•AwaitingDeployment: An agent push installation has been requested.

•DeployError: An agent push installation has failed.

•DeployedAwaitingContact: An agent push installation has occurred. The agent has not come online or reported back to the console.

•RegistrationFailed: An invalid agent registration was attempted or some date in the agent registration is incorrect.

•RegistrationTimeout: The time window for an agent registration has expired with no response from the agent.

•RegisteredAwaitingCheckIn: The agent has successfully registered but has not yet checked in.

•CheckInTimeout: A registered agent has failed to check in within the allotted time.

•Installed: Installation in complete and the first check-in operation has been completed.

•UninstallPending: The user has requested an uninstall of the agent but the agent has not yet checked in to receive the command.

•Uninstalled: The agent has been uninstalled.

Name

Type

Description

agentId

String

The agent ID.

frameworkVersion

String

Installed agent framework version.

installedPackages

String

The list of engines installed on the agent machine.

lastCheckIn

DateTime

The date and time of the most recent check in.

links

Links

Shows the related URLs that can be used to query for additional information.

machineName

String

The agent machine's host name.

reportedOn

DateTime

The time the information was gathered from the agent machine.

runningPolicyId

Guid

The agent's running policy ID.

runningPolicyVersion

UInt32

The version identifier of the agent policy that is running.