api: document store key limitation

1 files changed, 5 insertions, 1 deletions

diff --git a/docs/openapi.yaml b/docs/openapi.yaml
index ba66f08..b863553 100644
--- a/docs/openapi.yaml
+++ b/docs/openapi.yaml
@@ -984,7 +984,11 @@ components:
       name: key
       in: path
       required: true
-      description: Slash-separated store path, e.g. `settings/theme`.
+      description: |
+        Slash-separated store path, e.g. `settings/theme`. A key with `/` in it, or an
+        empty key, can't be named here (neither `%2F` nor `//` helps: the path is
+        split after decoding, and empty segments are `400`); such keys exist only
+        inside a value written at a parent path, and are read through that parent.
       schema:
         type: string
     conflicts: