Entuity Agents - RESTful API – Entuity

This article details instructions for three calls:

api/v7/agents/access (registering an agent with the server)
api/v7/agents (listing the agents registered with the server)
api/v7/agents/{agentId} (listing details of, updating, or deleting a registered agent)

Summary:

URL:

http(s)://{server-hostname}/api/v7/agents/access

Summary:

List the agents that are registered with the server.

URL:

http(s)://{server-hostname}/api/v7/agents

Summary:

List details of, update, or delete a registered agent.

URL:

http(s)://{server-hostname}/v7/api/agents/{agentId}

Entuity Agents

Method summary

POST Method - v7/agents/access

GET Method - v7/agents

GET Method - v7/agents/{agentId}

PUT Method - v7/agents/{agentId}

DELETE Method - v7/agents/{agentId}

Method summary

v7/agents/access

POST Method - register the new agent with the server.

v7/agents:

GET Method - list the agents that are registered with the server.

v7/agents/{agentId}:

GET Method - list details of a registered agent.
PUT Method - change the details of a registered agent.
DELETE Method - remove a registered agent from the server.

POST Method - v7/agents/access

Request parameters:

Name	Description
allowed	true or false. If true, the agent can be registered with the server. If false, the agent is denied (or forbidden from) registering with the server.
agentName	agent name.
accessURL	the public base URL used by the agent to connect to the Entuity server, in the format: http://entuity-server-ip-address/api/v7/eca

Response:

Name	Description
message	the installation token for the agent. Enter this token during the Entuity Agent installation process later when prompted for a registration token.

Example:

INPUT
curl -i -X POST "http://localhost/api/v7/agents/access" -u admin:admin -H 'content-type: application/json' -H -d '
{
  "allowed": true,
  "agentName" : "Agent 1",
  "accessURL" : "http://entuity-server-ip-address/api/v7/eca"
}

OUTPUT
Response:
{
    "message": "Installation Token: xxxxxxxxxxxxxx"
}

GET Method - v7/agents

List the agents that are registered with the server.

Response:

Name

Description

items

list of registered agent summary details:

agentId: agent identifier
ipAddress: IP address of the server
operatingSystem: operating system of the server
osUser: operating system user
publicKey: the public key used by the agent.
updaterVersion: version of the agent
agentName: agent name
statusCategory:
createTimeSec: the amount of time it took to create the agent, in seconds
installedApps: the applications installed on the agent

count

number of agents registered with the server.

Example:

INPUT
curl -i -X GET "http://localhost/api/v7/agents" -u admin:admin -H 'content-type: application/json'

OUTPUT
Response:
{
    "items": [
        {
            "agentId": "b143b765-ecfb-4318-83c2-a23b310e476a",
            "hostName": "PW0A89SY.PPIDomain.local",
            "ipAddress": "192.168.86.130",
            "operatingSystem": "Windows 10 Enterprise",
            "osUser": "PW0A89SY$",
            "publicKey": "MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAqT3UULW2ofrDLdjQ+6V89Yy4xnUoR7PHSxjqW0Xas+qyYCEg/k3r4uief0PGI+2AhnAMWxJX+IFWnO+p6g9QjxwuF/CadFgo9ld1temIYWWwM/IE1zyBBBezImtmFF2yvHlwlMmI8jQ2TBmRmJ2RFionfuWces0waY7S7r5YggpZx8McBNxc2zQZPu4bstUug0kErOYVChi4I22nC3FjrC4p+FAmtxPRIZ3UfJpLm09SuucfYw/OGY5dlvYg5AxWMOKR8UeKD5sNOIn2J4lIo2x2nfpZNc0SCi/Rfzli32vyICYJf1DPSy3V2bGftxPgrjdHJ6LQw0g0KB/MxONjnwIDAQAB",
            "updaterVersion": "1.0.0_20260316",
            "agentName": "ILR-agent-entuity",
            "statusCategory": 0,
            "createTimeSec": 1781126627,
            "installedApps": "agentupdater=agentupdater-win.x86-1.0.0_20260316, collector=collector-win.x86-1.0.0_20260316"
        }
    ],
    "count": 1
}

GET Method - v7/agents/{agentId}

List details of a registered agent.

Response:

Name	Description
statusCode	the agent status: OK: the agent registered successfully. EXISTS: an agent already exists with this ID. PENDING: the agent request is pending. FORBIDDEN: the agent is forbidden from accessing/registering with Entuity. FAILED: the agent registration request failed.
message	information about the agent status.
agentDetails	details of the agent: agentId: agent identifier ipAddress: IP address of the server operatingSystem: operating system of the server osUser: operating system user publicKey: the public key used by the agent. updaterVersion: version of the agent agentName: agent name statusCategory: createTimeSec: the amount of time it took to create the agent, in seconds installedApps: the applications installed on the agent
agentUserExists	true or false. Indicates whether there's a user account associated with the agent.
agentTokenExists	true or false. Indicates whether the agent has an installation token.

Example:

INPUT
curl -i -X GET "http://localhost/api/v7/agents/{agentId}" -u admin:admin -H 'content-type: application/json'

OUTPUT
{
    "statusCode": "OK",
    "message": "",
    "agentDetails": {
        "agentId": "b143b765-ecfb-4318-83c2-a23b310e476a",
        "hostName": "PW0A89SY.PPIDomain.local",
        "ipAddress": "192.168.86.130",
        "operatingSystem": "Windows 10 Enterprise",
        "osUser": "PW0A89SY$",
        "publicKey": "MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAqT3UULW2ofrDLdjQ+6V89Yy4xnUoR7PHSxjqW0Xas+qyYCEg/k3r4uief0PGI+2AhnAMWxJX+IFWnO+p6g9QjxwuF/CadFgo9ld1temIYWWwM/IE1zyBBBezImtmFF2yvHlwlMmI8jQ2TBmRmJ2RFionfuWces0waY7S7r5YggpZx8McBNxc2zQZPu4bstUug0kErOYVChi4I22nC3FjrC4p+FAmtxPRIZ3UfJpLm09SuucfYw/OGY5dlvYg5AxWMOKR8UeKD5sNOIn2J4lIo2x2nfpZNc0SCi/Rfzli32vyICYJf1DPSy3V2bGftxPgrjdHJ6LQw0g0KB/MxONjnwIDAQAB",
        "updaterVersion": "1.0.0_20260316",
        "agentName": "ILR-agent-entuity",
        "statusCategory": 0,
        "createTimeSec": 1781126627,
        "installedApps": "agentupdater=agentupdater-win.x86-1.0.0_20260316, collector=collector-win.x86-1.0.0_20260316"
    },
    "agentUserExists": true,
    "agentTokenExists": true
}

PUT Method - v7/agents/{agentId}

Change the details of a registered agent.

Request:

Specify the detail(s) of the registered agent that you want to edit. See the agentDetails parameters in GET - v7/agents/{agentId}.

Response:

Same as for GET - v7/agents/{agentId} earlier.

Example:

INPUT
curl -i -X PUT "http://localhost/api/v7/agents/{agentId}" -u admin:admin -H 'content-type: application/json' -H -d '\
'{
    "agentName": "New-agent-name",
}
'

OUTPUT
{
    "statusCode": "OK",
    "message": "",
    "agentDetails": {
        "agentId": "cd084400-94d9-42e6-ab4d-a606205b28b4",
        "hostName": "entuityagent.entuity.com",
        "ipAddress": "10.70.119.57",
        "operatingSystem": "Linux",
        "osUser": "root",
        "publicKey": "MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAyfVg/9nyBatXLeop+fan+BRX+JNuX4/UYUKlarHB2fwrOnZBfeX4/Lll5vsGv3Co5GPoAPDcsiAWPsV78p10+uaF4Yktm8c2S+s/XhgBfE+K8pHYzs0KtkBgiLg5FaC4+5sKZimu3qy4QHglK6/vL8lISkMT0FSw2oHn940apspbktm/vJSmVzIbDNAkgk9Y6/T+GMBngWfHvP+WB1QFvSgaPOZaW3Ty258vB/o2xWFojtB+Mp8whJbqa0QREeoFEvTXERp54Vn+JyyggoUc+Y5avBIC/juN0kJypWA9EIjERzgZNGHz32JqXo6CkC+aRAXYnwlz8HoT4NRQgBPtYwIDAQAB",
        "updaterVersion": "1.0.0_f555be5f",
        "agentName": "New-agent-name",
        "statusCategory": 0,
        "createTimeSec": 1771266590,
        "installedApps": "agentupdater=agentupdater-linux.x86-1.0.0_f555be5f, collector=collector-linux.x86-1.0.0_f555be5f"
    },
    "agentUserExists": true,
    "agentTokenExists": true
}

DELETE Method - v7/agents/{agentId}

Remove a registered agent from the server.

Request:

The ID of the object that is to be deleted.

Response:

“OK” message if the registered agent was removed successfully, an error status and message otherwise.

Examples:

A successful deletion:

INPUT
curl -i -X DELETE "http://localhost/api/v7/agents/{agentId}" -u admin:admin -H 'content-type: application/json'

OUTPUT
{
    "statusCode": "OK",
    "message": ""
}

A deletion failure:

INPUT
curl -i -X DELETE "http://localhost/api/v7/agents/{agentId}" -u admin:admin -H 'content-type: application/json'

OUTPUT

{
    "statusCode": "FAILED",
    "message": "Failed to delete Cloud Agent StormWorks object for objectId=273753: Association devices is not empty."
}