Server names and URL templating

Fern supports several extensions for configuring the servers block in your OpenAPI specification. Use x-fern-server-name to give servers human-readable names, then combine it with URL template variables and x-fern-default-url to support dynamic base URLs in generated SDKs.

x-fern-server-name

Use x-fern-server-name to give each server entry a human-readable name. Fern uses this name in the generated environments enum.

The x-fern-server-name extension is used to name your servers.

1
servers:
2
  - url: https://api.example.com
3
    x-fern-server-name: Production
4
  - url: https://sandbox.example.com
5
    x-fern-server-name: Sandbox

In a generated TypeScript SDK, you’d see:

1
export const ExampleEnvironment = {
2
  Production: "https://api.example.com",
3
  Sandbox: "https://sandbox.example.com",
4
} as const;
5
6
export type ExampleEnvironment = typeof ExampleEnvironment.Production;

Multiple base URLs

Different endpoints can target different servers. Add a servers block directly on an endpoint to override the top-level server for that path. Use x-fern-server-name to give each endpoint-level server a distinct name so Fern can group them correctly.

1
paths:
2
  /auth/token:
3
    post:
4
      servers:
5
        - url: https://auth.example.com
6
          x-fern-server-name: Auth

When Fern detects multiple named servers, the generated SDK client resolves each endpoint to the correct base URL automatically.

x-fern-server-name is also used alongside URL template variables, as shown below.

URL templating and x-fern-default-url

For APIs deployed across multiple regions, environments, or custom domains, you can define variable placeholders in the server url using {variable} syntax. Fern reads these variables and exposes them as configurable parameters in the generated SDK, so users can customize the base URL at runtime.

Since a templated URL like https://api.{region}.example.com/v1 isn’t valid on its own, use x-fern-default-url to provide a concrete fallback. This way, SDK users who don’t need to customize variables get a working client out of the box.

1
servers:
2
  - url: https://api.{region}.{environment}.example.com/v1
3
    description: Regional API server
4
    x-fern-server-name: Default
5
    x-fern-default-url: https://api.example.com/v1
6
    variables:
7
      region:
8
        default: us-east-1
9
        enum:
10
          - us-east-1
11
          - us-west-2
12
          - eu-west-1
13
      environment:
14
        default: prod
15
        enum:
16
          - prod
17
          - staging
18
          - dev

Each variable is defined under the variables map and supports the following fields:

• default — The fallback value used when the SDK user doesn’t provide one. This field is required by the OpenAPI specification.
• enum — An optional list of allowed values. When provided, Fern generates the variable as a typed enum in the SDK rather than an open string.