api_docs: Document feature level 286.

api_docs/changelog.md

@@ -20,6 +20,12 @@ format used by the Zulip server that they are interacting with.
 
 ## Changes in Zulip 10.0
 
+**Feature level 286**
+
+* [`POST /user_uploads`](/api/upload-file): Added `filename` field to
+  the response, which is closer to the original filename than the
+  basename of the `url` field in the response.
+
 **Feature level 285**
 
 * [`PATCH /messages/{message_id}`](/api/update-message): Added

zerver/openapi/zulip.yaml

@@ -8253,7 +8253,15 @@ paths:
                       filename:
                         type: string
                         description: |
-                          The filename that Zulip stored the upload as.
+                          The filename that Zulip stored the upload as. This usually
+                          differs from the basename of the URL when HTML escaping is
+                          required to generate a valid URL.
+
+                          Clients generating a Markdown link to a newly uploaded file
+                          should do so by combining the `url` and `filename` fields in the
+                          response as follows: `[{filename}]({url})`, with care taken to
+                          clean `filename` of `[` and `]` characters that might break
+                          Markdown rendering.
 
                           **Changes**: New in Zulip 10.0 (feature level 285).
                     example: