diff --git a/fern/products/api-def/api-def.yml b/fern/products/api-def/api-def.yml
index 36969fe38..52197fec1 100644
--- a/fern/products/api-def/api-def.yml
+++ b/fern/products/api-def/api-def.yml
@@ -49,6 +49,8 @@ navigation:
path: ./openapi/extensions/availability.mdx
- page: Base path
path: ./openapi/extensions/base-path.mdx
+ - page: Default values
+ path: ./openapi/extensions/default.mdx
- page: Enum descriptions, names, and availability
path: ./openapi/extensions/enums.mdx
slug: enum-descriptions-and-names
diff --git a/fern/products/api-def/openapi/extensions/default.mdx b/fern/products/api-def/openapi/extensions/default.mdx
new file mode 100644
index 000000000..c68b1b019
--- /dev/null
+++ b/fern/products/api-def/openapi/extensions/default.mdx
@@ -0,0 +1,77 @@
+---
+title: Default values
+headline: Default values (OpenAPI)
+description: Use `x-fern-default` to set client-side default values for path, header, and query parameters in generated SDKs.
+---
+
+The `x-fern-default` extension lets you specify a client-side default value for a path, header, or query parameter, including headers defined under [`x-fern-global-headers`](/learn/api-definitions/openapi/extensions/global-headers). When present, the generated SDK makes the parameter optional and automatically sends the default value if the caller omits it. `x-fern-default` supports `string` and `boolean` values; other types (such as numbers) are ignored.
+
+This is useful for pinning an API version header or a region path parameter while still allowing callers to override the value.
+
+
+ `x-fern-default` is supported for TypeScript, Python, Go, Java, C#, PHP, and Ruby SDKs.
+
+
+## Path parameters
+
+In the example below, the SDK sends `us-east-1` for `region` when the caller doesn't specify one.
+
+```yaml {9} title="openapi.yml"
+paths:
+ /regions/{region}/resources:
+ get:
+ operationId: list_resources
+ parameters:
+ - name: region
+ in: path
+ required: true
+ x-fern-default: "us-east-1"
+ schema:
+ type: string
+```
+
+## Headers
+
+In the example below, the SDK sends `2024-02-08` for `X-API-Version` when the caller doesn't specify one.
+
+```yaml {8} title="openapi.yml"
+paths:
+ /users:
+ get:
+ operationId: list_users
+ parameters:
+ - name: X-API-Version
+ in: header
+ x-fern-default: "2024-02-08"
+ schema:
+ type: string
+```
+
+## Query parameters
+
+In the example below, the SDK sends `false` for `verbose` when the caller doesn't specify one.
+
+```yaml {8} title="openapi.yml"
+paths:
+ /search:
+ get:
+ operationId: search
+ parameters:
+ - name: verbose
+ in: query
+ x-fern-default: false
+ schema:
+ type: boolean
+```
+
+## Global headers
+
+In the example below, the SDK sends `2024-02-08` for the `X-API-Version` global header when the caller doesn't specify one.
+
+```yaml {4} title="openapi.yml"
+x-fern-global-headers:
+ - header: X-API-Version
+ name: version
+ x-fern-default: "2024-02-08"
+```
+
diff --git a/fern/products/api-def/openapi/extensions/global-headers.mdx b/fern/products/api-def/openapi/extensions/global-headers.mdx
index af52eb191..d684a1b42 100644
--- a/fern/products/api-def/openapi/extensions/global-headers.mdx
+++ b/fern/products/api-def/openapi/extensions/global-headers.mdx
@@ -15,9 +15,11 @@ class Client:
def __init__(self, *, apiKey: str):
```
-To configure global headers, Fern will automatically pull out headers that are used in every request, or the majority of requests, and mark them as global.
+Fern automatically pulls out headers that are used in every request, or the majority of requests, and marks them as global.
-In order to label additional headers as global, or to alias the names of global headers, you can leverage the `x-fern-global-headers` extension:
+## In your OpenAPI spec
+
+To label additional headers as global, or to alias the names of global headers, use the `x-fern-global-headers` extension:
```yaml title="openapi.yml"
x-fern-global-headers:
@@ -26,10 +28,24 @@ x-fern-global-headers:
- header: userpool_id
optional: true
```
+
When you define global headers using `x-fern-global-headers`, you must [include them in your `x-fern-examples`](/api-definitions/openapi/extensions/request-response-examples).
+### Default values
+
+Set a client-side default value on a global header using [`x-fern-default`](/learn/api-definitions/openapi/extensions/default-values). The generated SDK makes the header optional and sends the default when the caller omits it:
+
+```yaml {4} title="openapi.yml"
+x-fern-global-headers:
+ - header: X-API-Version
+ name: version
+ x-fern-default: "2024-02-08"
+```
+
+## In `generators.yml`
+
Alternatively, you can add headers to the [`api` block in your `generators.yml` file](/learn/sdks/reference/generators-yml#headers):
```yaml title="generators.yml"
@@ -44,6 +60,8 @@ api:
type: optional
```
+## Generated SDK behavior
+
Both configurations yield the following client code:
```python
diff --git a/fern/products/api-def/openapi/extensions/overview.md b/fern/products/api-def/openapi/extensions/overview.md
index 0b691fd2e..f1dc736d3 100644
--- a/fern/products/api-def/openapi/extensions/overview.md
+++ b/fern/products/api-def/openapi/extensions/overview.md
@@ -20,6 +20,7 @@ The table below shows all available extensions and links to detailed documentati
| [`x-fern-bearer`](/api-definitions/openapi/authentication#bearer-security-scheme) | Customize bearer authentication parameter names and environment variables |
| [`x-fern-availability`](./availability) | Mark availability status (beta, generally-available, deprecated) |
| [`x-fern-base-path`](./base-path) | Set base path prepended to all endpoints |
+| [`x-fern-default`](./default-values) | Set client-side default values for path, header, and query parameters |
| [`x-displayName`](./tag-display-names) | Specify how tag names display in your API Reference |
| [`x-fern-enum`](./enum-descriptions-and-names) | Add descriptions, custom names, and deprecation status to enum values |
| [`x-fern-examples`](./request-response-examples) | Associate request and response examples |
diff --git a/fern/products/sdks/deep-dives/configure-global-headers.mdx b/fern/products/sdks/deep-dives/configure-global-headers.mdx
index 6a74b2a6b..f9aebfa2b 100644
--- a/fern/products/sdks/deep-dives/configure-global-headers.mdx
+++ b/fern/products/sdks/deep-dives/configure-global-headers.mdx
@@ -47,6 +47,8 @@ headers:
+You can also pin a [default value](/learn/api-definitions/openapi/extensions/default-values) on a global header so the SDK sends it automatically when the caller doesn't provide one.
+
For full configuration details, see the docs for your API definition format:
diff --git a/fern/products/sdks/deep-dives/generated-sdk.mdx b/fern/products/sdks/deep-dives/generated-sdk.mdx
index 7288fec5c..971fd8ce9 100644
--- a/fern/products/sdks/deep-dives/generated-sdk.mdx
+++ b/fern/products/sdks/deep-dives/generated-sdk.mdx
@@ -47,6 +47,10 @@ When the API returns a 4xx or 5xx status code, the SDK throws an error that incl
When you define webhooks in your API spec, Fern automatically [generates utilities that allow your users to verify webhook signatures](./webhook-signature-verification) and ensure events originate from your API.
+## Default parameter values
+
+You can configure [default values](/learn/api-definitions/openapi/extensions/default) for path, header, and query parameters, including headers defined under [`x-fern-global-headers`](/learn/api-definitions/openapi/extensions/global-headers). The SDK makes those parameters optional and sends the default when the caller doesn't provide one — useful for things like pinning an API version header or default region. Supported in TypeScript, Python, Go, Java, C#, PHP, and Ruby SDKs.
+
## Customization options
Your SDK users can configure individual requests using language-specific options: