docs: document send-optional-defaults playground setting

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`.
 
 <div style="position: relative; padding-bottom: 50.63657407407407%; height: 0;"><iframe src="https://www.loom.com/embed/a48d921459b54dde9652c3fcc85ebc54?sid=2c0b4f4d-7e24-4fc5-a617-8d933195bfec?hide_owner=true&hide_share=true&hide_title=true&hideEmbedTopBar=true" frameborder="0" webkitallowfullscreen mozallowfullscreen allowfullscreen style="position: absolute; top: 0; left: 0; width: 100%; height: 100%;"></iframe></div>
 

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`. 
@@ -428,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<string>`): 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`.
 
 </ParamField>
 

fern/products/docs/pages/changelog/2026-07-31.mdx

@@ -0,0 +1,7 @@
+## Send defaults for optional parameters in the API Explorer
+
+<ChangelogTags>api-reference, docs.yml</ChangelogTags>
+
+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.
+
+<Button intent="none" outlined rightIcon="arrow-right" href="/learn/docs/api-references/customize-api-reference-layout#sending-defaults-for-optional-parameters">Read the docs</Button>