From 602045c2978ef5aebc1a488b065f94978a7ba918 Mon Sep 17 00:00:00 2001
From: Alex Demidoff <alexander.demidoff@percona.com>
Date: Fri, 19 Jan 2024 15:01:07 +0000
Subject: [PATCH] PMM-12811 document the change

---
 docs/api/inventory/change-agent.md | 67 ++++++++++++++++++++++++++++++
 1 file changed, 67 insertions(+)
 create mode 100644 docs/api/inventory/change-agent.md

diff --git a/docs/api/inventory/change-agent.md b/docs/api/inventory/change-agent.md
new file mode 100644
index 0000000000..3d66525686
--- /dev/null
+++ b/docs/api/inventory/change-agent.md
@@ -0,0 +1,67 @@
+---
+title: Change Agent Attributes
+slug: changeagent
+category: 626de009b977e3003179f7dd
+---
+
+## Change Agent Attributes
+
+This section describes how to change Agent attributes.
+
+Please note that not all attrbutes can be chaged. For example, you cannot change the Agent type nor its ID.
+
+In PMM versions prior to 3.0.0, we featured a separate API call for each Agent type. Starting with PMM 3.0.0, we offer a single API endpoint for all Agent types. While previously the Agent type was defined by the endpoint, i.e. `/v1/inventory/Agents/ChangeMySQLdExporter`, now the Agent type must be specified as the top-level property of the request payload. Along with this single API endpoint, we are deprecating individual API endpoints for each Agent type.
+
+Let's see how to change Agent attributes using the old and new API calls. The goal of this sample API call is to enable the agent, make it work in push mode, and remove a few custom labels from it. 
+
+Old API call:
+
+```shell
+curl --insecure -X POST \
+  -H 'Authorization: Basic YWRtaW46YWRtaW4=' \
+	-H 'Accept: application/json' \
+	-H 'Content-Type: application/json' \
+	--url https://127.0.0.1/v1/inventory/Agents/ChangeMySQLdExporter \
+	--data '
+{
+  "agent_id": "/agent_id/13519ec9-eedc-4d21-868c-582e146e1d0e",
+  "common": {
+    "enable":  true,
+    "custom_labels": {
+      "department":  "sales",
+      "replication_set": "db-sales-prod-1-rs1",
+    },
+    remove_custom_labels: true,
+    enable_push_metrics: true,
+  }
+}
+'
+```
+
+New API call:
+
+```shell
+curl --insecure -X POST \
+  -H 'Authorization: Basic YWRtaW46YWRtaW4=' \
+	-H 'Accept: application/json' \
+	-H 'Content-Type: application/json' \
+	--url https://127.0.0.1/v1/inventory/Agents/Add \
+	--data '
+{
+  "mysqld_exporter": {
+    "agent_id": "/agent_id/13519ec9-eedc-4d21-868c-582e146e1d0e",
+    "common": {
+      "enable":  true,
+      "custom_labels": {
+        "department":  "sales",
+        "replication_set": "db-sales-prod-1-rs1",
+      },
+      remove_custom_labels: true,
+      enable_push_metrics: true,
+    }
+  }
+}
+'
+```
+
+To get the authentication token, please visit [this page](ref:authentication).