GET | List a Network Connector agent by [id]

Description

Retrieve the name, port, status, and fingerprint of a single agent of the Network Connector by its identification code.

The endpoint returns active and inactive agents. The active field shows the agent's status.

The agent's id is the value that the network_connector_id field of a device accepts. A device accepts only an active agent. In the device request, send the id as an integer.

Prerequisites

An application with the PAM resource permission set to Read-only or Read and write, granted by the administrator in A2A. For more information, access How to manage authorizations in A2A for API v2.
A valid OAuth 2.0 access token. For more information, access How to authenticate an application in A2A.

Request

GET /api/v2/platform/network-connector/agents/{agent_id}

Path parameters

Field	Type	Required	Description
`agent_id`	integer	Yes	Unique identification code of the agent. Accepts digits only. To find it, access GET \| List all Network Connector agents.

Query parameters

Field	Type	Description
`fields`	string	Restricts the response to the listed fields. Accepts `id`, `network_connector_agent.name`, `network_connector_agent.port`, `network_connector_agent.active`, and `network_connector_agent.fingerprint`. The `id` field is always returned.

For the full field projection syntax, access API v2 - Conventions and shared behaviors.

Example request

GET {{url}}/api/v2/platform/network-connector/agents/2

Response

HTTP/1.1 200 OK

The endpoint supports conditional reads. Send the ETag value from a previous response in the If-None-Match header. If the agent has not changed, the response is 304 Not Modified with no body.

Example response body

{
    "data": {
        "id": "2",
        "network_connector_agent": {
            "name": "agent-rj-01",
            "port": "30001",
            "active": true,
            "fingerprint": "EXAMPLE-FINGERPRINT-0001"
        }
    },
    "meta": {
        "links": {
            "self": "/api/v2/platform/network-connector/agents/2"
        },
        "actions": {
            "deactivate": "/api/v2/platform/network-connector/agents/2/deactivate"
        }
    }
}

Response body fields

Field	Type	Description
`data`	object	The agent.
`data.id`	string	Unique identification code of the agent, returned as a string. Use this value in the `network_connector_id` field of a device.
`data.network_connector_agent`	object	Attributes of the agent.
`data.network_connector_agent.name`	string	Name of the agent.
`data.network_connector_agent.port`	string	Port of the agent, returned as a string. Can be `null`.
`data.network_connector_agent.active`	boolean	`true` when the agent is active, `false` when it is deactivated.
`data.network_connector_agent.fingerprint`	string	Value used to install the agent. Store it securely and share it only with whoever installs the agent. Can be `null`.
`meta`	object	Response metadata.
`meta.links.self`	string	URL of the current request.
`meta.actions.deactivate`	string	Path to deactivate the agent. Returned only when the agent is active. For more information, access POST \| Deactivate Network Connector agent.
`meta.actions.activate`	string	Path to activate the agent. Returned only when the agent is deactivated. For more information, access POST \| Activate Network Connector agent.

Errors

HTTP code	Message	Possible cause	Solution
`404`	`api.resource.not_found`	The agent does not exist.	Check the identification code sent in the path. To find the agents, access GET \| List all Network Connector agents.
`404`	`api.route.not_found`	The `agent_id` value is not made up of digits only, such as `abc`, `-1`, or `1.5`.	Send the agent's identification code using digits only.
`422`	`api.fields.invalid`	The `fields` parameter requested a field that does not exist.	Check the field names in Query parameters.

For authentication and permission errors and the 403 versus 404 policy, access API v2 - Conventions and shared behaviors.