From 0f75537004a9d9893d5a753ebb2934d1088b27cc Mon Sep 17 00:00:00 2001
From: petrsnd <petrsnd@gmail.com>
Date: Thu, 21 May 2026 11:12:07 -0600
Subject: [PATCH] Clarify params keyword and document HiddenString usage in
 api-patterns skill

---
 .agents/skills/api-patterns/SKILL.md | 28 +++++++++++++++++++++++-----
 1 file changed, 23 insertions(+), 5 deletions(-)

diff --git a/.agents/skills/api-patterns/SKILL.md b/.agents/skills/api-patterns/SKILL.md
index f208d60..74abc1e 100644
--- a/.agents/skills/api-patterns/SKILL.md
+++ b/.agents/skills/api-patterns/SKILL.md
@@ -299,6 +299,21 @@ private_key = A2AContext.quick_retrieve_private_key(
 | `broker_access_request(api_key, access_request)` | `str` | Submit an access request |
 | `get_retrievable_accounts(*, filter=None)` | `list[dict]` | List accounts (uses cert auth) |
 
+### HiddenString return values
+
+Methods that return secrets (like `A2AContext.retrieve_password()`) return a
+`HiddenString` object that displays as `***` when printed, formatted, or
+converted with `str()`. To access the raw value:
+
+```python
+password = ctx.retrieve_password(api_key)
+print(password)          # prints: ***
+print(password.value)    # prints the actual password string
+raw = password.value
+```
+
+This prevents accidental credential leakage in logs or REPL output.
+
 ### A2A Authorization Header
 
 A2A requests use `Authorization: A2A <apiKey>` (not Bearer).
@@ -336,15 +351,18 @@ Set these when the appliance uses a certificate signed by an internal CA.
 
 ## Common Patterns
 
-### GET with query parameters
+### Query parameters
+
+Use the `params` keyword argument (not `parameters`) to pass query string values:
 
 ```python
-users = client.get(
-    Service.CORE, "Users",
-    params={"filter": "UserName eq 'admin'", "fields": "Id,UserName"},
-).json()
+users = client.get(Service.CORE, "Users", params={"fields": "Id,Name", "filter": "Disabled eq false"})
+assets = client.get(Service.CORE, "Assets", params={"filter": "Name eq 'MyAsset'"})
 ```
 
+> **Note:** The keyword is `params` (matching the `requests` library convention),
+> not `parameters` (which is the .NET SDK's name for the same concept).
+
 ### POST with JSON body
 
 ```python