PATCH | Update device

Description

Update selected fields of a device registered in PAM Core using the v2 API. The endpoint follows JSON Merge Patch semantics (RFC 7396): only the fields you send are changed, and the fields you omit are preserved. To replace the entire device, access PUT | Update device instead.

Prerequisites

• Authorization with write permission to PAM Core granted by the administrator in A2A. For more information, access How to manage authorizations in A2A.
• The current ETag of the device, required in the If-Match header. Obtain it from GET | List a device.
• The device must be active. Write operations on an inactive device return 409. To activate it, access POST | Activate device.

Request

PATCH /api/v2/platform/devices/{id}

Path parameters

Request headers

Request body

Every field is optional. A field you send replaces the current value; a field you send as null removes the value; a field you omit is left untouched. Array fields are replaced as a whole, not merged item by item.

Example request

PATCH {{url}}/api/v2/platform/devices/55

Headers

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

Body

{
    "criticality": "low",
    "tags": ["prod", "finance", "critical"],
    "domain_name": null
}

Response

HTTP/1.1 200 OK
ETag: "v4"

The ETag header holds the new version of the device. Use this value in the If-Match header of the next write operation.

Example response body

The response returns the complete device in the same format as GET | List a device, including the fields the request didn't touch.

{
    "data": {
        "id": "55",
        "device": {
            "name": "db-prod-01",
            "address": "10.10.10.10",
            "active": true,
            "type": "Server",
            "vendor": "Oracle",
            "product": "Oracle Linux VM",
            "site": "SP-DC1",
            "domain_name": null,
            "tags": ["prod", "finance", "critical"],
            "criticality": "low",
            "owner": {
                "name": "John Doe"
            },
            "administrator_group": null,
            "enable_remote_app": true,
            "network_connector": {
                "id": "12",
                "name": "NC-SP-01",
                "port": "50001"
            },
            "connectivities": [
                {
                    "protocol": "SSH",
                    "port": 22,
                    "connectable": true
                }
            ],
            "session_settings": [
                {
                    "connectivity": "SSH",
                    "expected_expression": "$",
                    "fill_in_value": "sudo su"
                }
            ]
        }
    },
    "meta": {
        "links": {
            "self": "/api/v2/platform/devices/55"
        },
        "actions": {
            "deactivate": "/api/v2/platform/devices/55/deactivate"
        }
    }
}

Response body fields

The response returns the updated device with the same fields as GET | List a device. Access that article for the full field tables.

Errors

Example error response

422 a forbidden field was sent in the body:

{
    "error": {
        "code": "patch.field.not_allowed",
        "message": "Field 'active' cannot be modified via PATCH."
    }
}

Authentication errors

Related documents

• API v2 — Conventions and shared behaviors
• PUT | Update device
• GET | List a device
• POST | Create device
• How to manage authorizations in A2A