From 03b7305906eb22c0f1e8b0b3ccea3056236899da Mon Sep 17 00:00:00 2001
From: Mladen Jablanovic <mladen.jablanovic@phrase.com>
Date: Thu, 19 Feb 2026 14:50:13 +0100
Subject: [PATCH] docs(API): document correct way of passing format_options

---
 doc/compiled.json                  | 7 ++++++-
 paths/locale_downloads/create.yaml | 9 +++++++--
 2 files changed, 13 insertions(+), 3 deletions(-)

diff --git a/doc/compiled.json b/doc/compiled.json
index a490b9ad..ca7fe7ad 100644
--- a/doc/compiled.json
+++ b/doc/compiled.json
@@ -9119,7 +9119,12 @@
                     "example": true
                   },
                   "format_options": {
-                    "description": "Additional formatting and render options. See the [format guide](https://support.phrase.com/hc/en-us/sections/6111343326364) for a list of options available for each format. Specify format options like this: `...&format_options[foo]=bar`",
+                    "description": "Additional formatting and render options. See the [format guide](https://support.phrase.com/hc/en-us/sections/6111343326364)\nfor a list of options available for each format. Pass format options as a JSON object with key-value pairs corresponding\nto the option name and value. For example, to include comments in a Gettext file, pass `{\"include_comments\": true}`.\n",
+                    "example": {
+                      "format_options": {
+                        "foo": "bar"
+                      }
+                    },
                     "type": "object",
                     "properties": {}
                   },
diff --git a/paths/locale_downloads/create.yaml b/paths/locale_downloads/create.yaml
index a21ce790..5d41312f 100644
--- a/paths/locale_downloads/create.yaml
+++ b/paths/locale_downloads/create.yaml
@@ -48,8 +48,13 @@ requestBody:
             type: boolean
             example: true
           format_options:
-            description: 'Additional formatting and render options. See the [format guide](https://support.phrase.com/hc/en-us/sections/6111343326364) for a list of options available for each format. Specify format options like this: `...&format_options[foo]=bar`'
-            # example:
+            description: |
+              Additional formatting and render options. See the [format guide](https://support.phrase.com/hc/en-us/sections/6111343326364)
+              for a list of options available for each format. Pass format options as a JSON object with key-value pairs corresponding
+              to the option name and value. For example, to include comments in a Gettext file, pass `{"include_comments": true}`.
+            example:
+              format_options:
+                foo: bar
             type: object
             properties: {}
           encoding: