> For clean Markdown content of this page, append .md to this URL. For the complete documentation index, see https://buildwithfern.com/learn/llms.txt.

# Request + response examples

> Configure OpenAPI request and response examples with x-fern-examples. Associate path parameters, query parameters, and responses in your API definition.

Fern generates realistic examples automatically using [AI-generated examples](/learn/docs/ai-features/ai-examples), enabled by default. Use `x-fern-examples` to manually define specific values, associate request and response pairs that OpenAPI's separate example fields can't link, or define multiple named examples for an endpoint.

Manual examples take priority over AI-generated ones, and you can [disable AI examples entirely](/learn/docs/configuration/site-level-settings#ai-examplesenabled).

## Structure

`x-fern-examples` is an array. Each element can contain `path-parameters`, `query-parameters`, `headers`, `request`, and `response` values that are all associated. Optionally, add a `name` field to provide a descriptive label.

The `request` and `response` values use different shapes:

* `request` holds the request body properties directly.
* `response` requires a nested `body` key containing the response body properties.

Examples must include any headers declared with the [`x-fern-global-headers` extension](/learn/api-definitions/openapi/extensions/global-headers). Place them under `headers` alongside `path-parameters` and `request`.

An endpoint with path parameters:

**`openapi.yml`**

```yaml title="openapi.yml"
paths:
  /users/{userId}:
    get:
      x-fern-examples:
        - name: Get user 1234 # Optional descriptive label
          headers:
            custom_api_key: "capi_12345" # header defined using x-fern-global-headers extension
            userpool_id: "pool_67890"    # header defined using x-fern-global-headers extension
          path-parameters:
            userId: user-1234
          response:
            body:
              name: Foo
              ssn: 1234
```

An endpoint with a request body:

**`openapi.yml`**

```yaml title="openapi.yml"
paths:
  /users:
    post:
      x-fern-examples:
        - name: Create user
          request:
            name: Alice
            email: alice@example.com
          response:
            body:
              id: user-5678
              name: Alice
              email: alice@example.com
```

## Code samples

Fern generators automatically add SDK code samples. To specify custom code samples for an example, use `code-samples`.

Each code sample uses one of two keys to identify the language:

* `sdk` — for a language that maps to a Fern-supported SDK tab: `curl`, `python`, `javascript`, `typescript`, `go`, `ruby`, `csharp`, `java`, `js`, `node`, `ts`, `nodets`, `golang`, `dotnet`, `jvm`, `c#`.
* `language` — for any other language, or when you want to include an `install` command.

#### Using sdk

**`openapi.yml`**

```yaml title="openapi.yml" {11-16}
paths:
  /users/{userId}:
    get:
      x-fern-examples:
        - path-parameters:
            userId: user-1234
          response:
            body:
              name: Foo
              ssn: 1234
          code-samples:
            - sdk: typescript
              code: |
                import { UserClient } from "...";

                client.users.get("user-1234")
```

#### Using language

**`openapi.yml`**

```yaml title="openapi.yml" {11-18}
paths:
  /users/{userId}:
    get:
      x-fern-examples:
        - path-parameters:
            userId: user-1234
          response:
            body:
              name: Foo
              ssn: 1234
          code-samples:
            - language: php
              install: composer require acme/sdk
              code: |
                use Acme\Client;

                $client = new Client();
                $client->users->get("user-1234");
```

## Convert to native OpenAPI examples

To make `x-fern-examples` work with non-Fern OpenAPI tools, run [`fern api enrich`](/learn/cli-api-reference/cli-reference/general-commands#fern-api-enrich) to convert them into native OpenAPI example fields.

> Configure OpenAPI request and response examples with x-fern-examples. Associate path parameters, query parameters, and responses in your API definition.