From 64ac1228a78fb54435f7e070fceafc2ad46c0c6e Mon Sep 17 00:00:00 2001
From: Jonas Alves <jonas@absmartly.com>
Date: Sat, 12 Sep 2026 09:34:15 +0100
Subject: [PATCH 1/2] docs(readme): show --show-request example for custom
 field payloads
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

A customer support case (FT-2207) revealed confusion over the exact
wire shape for custom_section_field_values on experiment update. The
CLI already builds the correct shape, but nothing showed how to see
it — add a verified --show-request example right next to the custom
field docs.
---
 README.md | 23 +++++++++++++++++++++++
 1 file changed, 23 insertions(+)

diff --git a/README.md b/README.md
index 5da6228..9785ad6 100644
--- a/README.md
+++ b/README.md
@@ -642,6 +642,29 @@ abs experiments restart 123 --hypothesis "New iteration"
 abs experiments create --name test --field "Hypothesis=We believe X"
 ```
 
+Custom field values are sent to the API as an object keyed by each field's numeric id (e.g. `{"75": {"type": "boolean", "value": "false"}}`), not as an array — the CLI builds this shape for you, so you never need to construct it by hand. If you're calling the API directly (e.g. from your own script or a custom MCP server) and want to see the exact payload the CLI sends, add `--show-request`:
+
+```bash
+abs experiments update 123 --field "Hypothesis=Updated hypothesis" --show-request
+# → PUT https://your-instance.absmartly.io/experiments/123
+#   Accept: application/json
+#   Content-Type: application/json
+#   Authorization: Api-Key ***
+#   User-Agent: absmartly-cli/1.14.0
+#
+#   {
+#     "id": 123,
+#     "data": {
+#       ...
+#       "custom_section_field_values": {
+#         "12": { "type": "string", "value": "Updated hypothesis" }
+#       }
+#     }
+#   }
+```
+
+This is the fastest way to confirm the exact shape a working request has, if you're getting an "Unknown or read-only fields" or "custom field values are required" error while integrating directly against the REST API.
+
 #### Summary output
 
 All `list` and `get` commands return summarized output by default. Use `--raw` for the full API response.

From 9a38e53f42b90aefcd7a9193bac36804563b4b9a Mon Sep 17 00:00:00 2001
From: Jonas Alves <jonas@absmartly.com>
Date: Sat, 12 Sep 2026 09:35:38 +0100
Subject: [PATCH 2/2] docs(readme): drop redundant follow-up sentence after
 --show-request example

---
 README.md | 2 --
 1 file changed, 2 deletions(-)

diff --git a/README.md b/README.md
index 9785ad6..63f2ef0 100644
--- a/README.md
+++ b/README.md
@@ -663,8 +663,6 @@ abs experiments update 123 --field "Hypothesis=Updated hypothesis" --show-reques
 #   }
 ```
 
-This is the fastest way to confirm the exact shape a working request has, if you're getting an "Unknown or read-only fields" or "custom field values are required" error while integrating directly against the REST API.
-
 #### Summary output
 
 All `list` and `get` commands return summarized output by default. Use `--raw` for the full API response.