PATCH | Update Network Connector agent

Description

Partially update an active Network Connector agent. Send only the fields to change; the name is the only editable field.

The body follows JSON Merge Patch (RFC 7396). Updating does not change the agent's id, port, or fingerprint. To replace the editable data in full, use PUT | Update Network Connector agent.

Prerequisites

An application with the PAM resource permission set to 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.
An active agent. A deactivated agent returns 409. To activate it, access POST | Activate Network Connector agent.

Request

PATCH /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.

Headers

Header	Required	Value
`Content-Type`	Yes	`application/merge-patch+json`
`If-Match`	Yes	`ETag` value of the agent's current state.

To get the agent's current ETag, read the agent with GET | List a Network Connector agent by [id] and copy the ETag header of the response.

Request body

Field	Type	Required	Description
`name`	string	No	New name of the agent. Leading and trailing spaces are removed. Maximum: 255 characters. Must be unique among the agents of the Network Connector, including deactivated agents. Does not accept `null`.

An empty body or {} changes nothing and returns the current agent. Sending id, port, active, or fingerprint returns 422.

Example request

PATCH {{url}}/api/v2/platform/network-connector/agents/12

Content-Type: application/merge-patch+json
If-Match: "9b2f6c0d4e8a1f3b7c5d2e9a0b4c6d8e"

{
    "name": "agent-rj-branch"
}

Response

HTTP/1.1 200 OK

The response includes the ETag header with the agent's new state. Use it in the next update.

Example response body

{
    "data": {
        "id": "12",
        "network_connector_agent": {
            "name": "agent-rj-branch",
            "port": "30003",
            "active": true,
            "fingerprint": "EXAMPLE-FINGERPRINT-0003"
        }
    },
    "meta": {
        "links": {
            "self": "/api/v2/platform/network-connector/agents/12"
        }
    }
}

Response body fields

The response has the same fields as PUT | Update Network Connector agent.

Field	Type	Description
`data`	object	The updated agent.
`data.id`	string	Unique identification code of the agent, returned as a string.
`data.network_connector_agent`	object	Attributes of the agent.
`data.network_connector_agent.name`	string	Name of the agent after the update.
`data.network_connector_agent.port`	string	Port of the agent, returned as a string. Unchanged.
`data.network_connector_agent.active`	boolean	Always `true`, because only active agents can be updated.
`data.network_connector_agent.fingerprint`	string	Value used to install the agent. Unchanged. Store it securely and share it only with whoever installs the agent. Can be `null`.
`meta`	object	Navigation links.
`meta.links.self`	string	Path of the agent.

Errors

HTTP code	Message	Possible cause	Solution
`400`	`api.request.bad_request`	The body is not valid JSON.	Check the payload syntax.
`403`	`api.auth.insufficient_permission`	The application's PAM resource permission is Read-only.	Ask the administrator to set the PAM resource permission to Read and write in A2A.
`404`	`api.resource.not_found`	The agent does not exist.	Check the identification code sent in the path.
`404`	`api.route.not_found`	The `agent_id` value is not made up of digits only.	Send the agent's identification code using digits only.
`409`	`api.resource.inactive`	The agent is deactivated.	Activate the agent with POST \| Activate Network Connector agent, then resend the request.
`412`	`api.precondition.failed`	The `If-Match` value does not match the agent's current state. The agent changed after you read it.	Read the agent again, then resend the request with the new `ETag`.
`415`	`api.request.unsupported_media_type`	The `Content-Type` header is not `application/merge-patch+json`.	Send `Content-Type: application/merge-patch+json`.
`422`	`api.validation.invalid_type`	`name` is not a string, or is `null`.	Send `name` as a string.
`422`	`api.validation.required_field`	`name` is empty or contains only spaces.	Send a name for the agent.
`422`	`api.validation.invalid_value`	`name` has more than 255 characters.	Send a name with up to 255 characters.
`422`	`api.validation.duplicate`	Another agent, active or deactivated, already uses the name.	Choose a different name.
`422`	`patch.field.not_allowed`	The body contains `id`, `port`, `active`, or `fingerprint`.	Send only `name`. To change the agent's status, use POST \| Activate Network Connector agent or POST \| Deactivate Network Connector agent.
`422`	`api.validation.unknown_field`	The body contains a field that is not part of the contract.	Send only `name`.
`428`	`api.precondition.required`	The request does not have the `If-Match` header.	Send the agent's current `ETag` in the `If-Match` header.

For authentication errors, rate limits, and the error response format, access API v2 - Conventions and shared behaviors.

Example error response

415 the request used application/json:

{
    "code": "api.request.unsupported_media_type",
    "message": "Content-Type must be 'application/merge-patch+json' for PATCH requests.",
    "details": null
}