Request + response examples

Fern generates realistic examples automatically using AI-generated 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.

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.

An endpoint with path parameters:

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:

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

Schema-level examples

Fern also reads native OpenAPI examples, with no extension required. When a request or response body has no example or examples on its media type object, Fern resolves the body schema (following $ref chains) and collects its schema-level example and examples entries. If that yields more than one example, each becomes a selectable example in the API Reference, labelled Example 1, Example 2, and so on. A schema with zero or one example produces a single example, as before.

paths:
  /jobs/{jobId}:
    get:
      responses:
        '200':
          description: The job status
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobStatus'
components:
  schemas:
    JobStatus:
      type: object
      properties:
        status:
          type: string
        async_job_id:
          type: string
        result:
          type: object
      examples:
        - status: pending
          async_job_id: job_01HZY
        - status: complete
          result: { total: 42 }

When an endpoint defines examples in more than one place, Fern uses the first source that applies:

1. x-fern-examples on the operation.
2. example or examples on the request or response media type object.
3. Schema-level example and examples on the body schema.
4. An autogenerated example.

In the API Reference, the response pane has a status-code dropdown (for example, 200 Successful). When the selected status code has several examples, a second dropdown appears next to it to switch between them; changing the selected example updates only the response body.

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.

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")

Convert to native OpenAPI examples

To make x-fern-examples work with non-Fern OpenAPI tools, run fern api enrich to convert them into native OpenAPI example fields.