From d9fbcca0ed4370be173e4854e0cad402e713d636 Mon Sep 17 00:00:00 2001
From: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
Date: Fri, 31 Jul 2026 17:08:50 +0000
Subject: [PATCH 1/2] docs: document send-optional-defaults playground setting
Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
---
.../docs/pages/api-references/api-explorer.mdx | 2 +-
.../docs/pages/api-references/customize-api-ref.mdx | 13 ++++++++++++-
fern/products/docs/pages/changelog/2026-07-31.mdx | 7 +++++++
3 files changed, 20 insertions(+), 2 deletions(-)
create mode 100644 fern/products/docs/pages/changelog/2026-07-31.mdx
diff --git a/fern/products/docs/pages/api-references/api-explorer.mdx b/fern/products/docs/pages/api-references/api-explorer.mdx
index e370c862ec..6c9c2162cc 100644
--- a/fern/products/docs/pages/api-references/api-explorer.mdx
+++ b/fern/products/docs/pages/api-references/api-explorer.mdx
@@ -7,7 +7,7 @@ subtitle: Reduce "time to 200" by allowing users to make real calls to your API
Fern's API Explorer allows users to make authenticated requests to your API without ever leaving your documentation.
## Autopopulate with examples
-Fern will automatically populate the fields of the endpoint with the values set in your API specification.
+Fern will automatically populate the fields of the endpoint with the values set in your API specification. Optional parameters that declare a default are only pre-filled and sent when you enable [`playground.send-optional-defaults`](/learn/docs/api-references/customize-api-reference-layout#sending-defaults-for-optional-parameters) in your `docs.yml`.
diff --git a/fern/products/docs/pages/api-references/customize-api-ref.mdx b/fern/products/docs/pages/api-references/customize-api-ref.mdx
index 5184e5c180..eb1b964b8b 100644
--- a/fern/products/docs/pages/api-references/customize-api-ref.mdx
+++ b/fern/products/docs/pages/api-references/customize-api-ref.mdx
@@ -220,7 +220,7 @@ You can hide an endpoint from the API Reference by setting `hidden` to `true`. T
### Setting API Explorer options
-The `playground` property sets two API Explorer options: `oauth` enables the [OAuth client-credentials flow](/learn/api-definitions/openapi/authentication), and `environments` restricts which server environments are available (an empty list disables the Explorer). Set it on the `- api` entry to apply a default across all endpoints, then override it on a section or endpoint in `layout`:
+The `playground` property sets three API Explorer options: `oauth` enables the [OAuth client-credentials flow](/learn/api-definitions/openapi/authentication), `environments` restricts which server environments are available (an empty list disables the Explorer), and `send-optional-defaults` pre-fills and sends declared defaults for optional parameters. Set it on the `- api` entry to apply a default across all endpoints, then override it on a section or endpoint in `layout`:
```yaml title="docs.yml" {4-5,8-9,13-14}
navigation:
@@ -237,6 +237,17 @@ navigation:
oauth: false # Override for this endpoint
```
+### Sending defaults for optional parameters
+
+The API Explorer always sends the declared `default` (or [`x-fern-default`](/learn/api-definitions/openapi/extensions/default-values)) of a required parameter. Optional header, query, and path parameters are left empty unless `send-optional-defaults` is `true`, which pre-fills their declared default and includes it in the request. This is useful when an API expects an optional header, such as a mock-response selector, on every request. It defaults to `false`.
+
+```yaml title="docs.yml" {3-4}
+navigation:
+ - api: API Reference
+ playground:
+ send-optional-defaults: true
+```
+
### Adding custom sections
You can add arbitrary folders in the sidebar by adding a `section` to your API Reference layout. A section can comprise entire groups of endpoints, individual endpoints, or even just Markdown pages. Sections can be customized by adding properties like a `icon`, `summary`, `slug` (or `skip-slug`), `availability`, and `contents`.
diff --git a/fern/products/docs/pages/changelog/2026-07-31.mdx b/fern/products/docs/pages/changelog/2026-07-31.mdx
new file mode 100644
index 0000000000..c19c8e6b51
--- /dev/null
+++ b/fern/products/docs/pages/changelog/2026-07-31.mdx
@@ -0,0 +1,7 @@
+## Send defaults for optional parameters in the API Explorer
+
+api-reference, docs.yml
+
+You can now have the API Explorer pre-fill and send the declared `default` (or `x-fern-default`) of optional header, query, and path parameters. Set `playground.send-optional-defaults: true` in `docs.yml` on an API, section, or endpoint. It's off by default, so existing sites are unchanged.
+
+
From e64fa28405510c1966f754e9d232c05a9e44c041 Mon Sep 17 00:00:00 2001
From: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
Date: Fri, 31 Jul 2026 17:14:52 +0000
Subject: [PATCH 2/2] docs: add send-optional-defaults to playground options
reference
Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
---
fern/products/docs/pages/api-references/customize-api-ref.mdx | 1 +
1 file changed, 1 insertion(+)
diff --git a/fern/products/docs/pages/api-references/customize-api-ref.mdx b/fern/products/docs/pages/api-references/customize-api-ref.mdx
index eb1b964b8b..f079d833f6 100644
--- a/fern/products/docs/pages/api-references/customize-api-ref.mdx
+++ b/fern/products/docs/pages/api-references/customize-api-ref.mdx
@@ -439,6 +439,7 @@ The following properties can be set on the `- api` entry in your `docs.yml` navi
- `oauth` (`boolean`): When `true`, enables the [OAuth client-credentials flow](/learn/docs/api-references/api-explorer#authentication) in the API Explorer.
- `environments` (`list`): Restricts which server environments are available in the API Explorer. An empty list disables the Explorer.
+ - `send-optional-defaults` (`boolean`): When `true`, [pre-fills and sends the declared defaults](#sending-defaults-for-optional-parameters) of optional header, query, and path parameters. Defaults to `false`.