Environments

You can specify the environments where your server is deployed.

Single URL environments

name: api
environments:
  Production: https://www.yoursite.com
  Staging:
    docs: This staging environment is helpful for testing!
    url: https://www.staging.yoursite.com

Multiple URLs per environment

You can specify multiple URLs per environment. This is helpful if you have a microservice architecture, and you want a single SDK to interact with multiple servers.

environments:
  Production:
    urls:
      Auth: https://auth.yoursite.com
      Plants: https://plants.yoursite.com
  Staging:
    urls:
      Auth: https://auth.staging.yoursite.com
      Plants: https://plants.staging.yoursite.com

If you choose to use this feature, you must specify a url for each service you define:

service:
  url: Auth
  base-path: /auth
  ...

Default environment

You can also provide a default environment:

name: api
environments:
  Production: https://www.yoursite.com
  Staging:
    docs: This staging environment is helpful for testing!
    url: https://www.staging.yoursite.com
default-environment: Production

Base URL from an environment variable

Set base-url-env to the name of an environment variable that the generated SDK reads for its base URL, the same way auth credentials can default from environment variables. This lets each deployment (staging, production, self-hosted) point the SDK at a different host without passing a base URL in code.

name: api
environments:
  Production: https://www.yoursite.com
  Staging: https://www.staging.yoursite.com
default-environment: Production
base-url-env: PLANTS_API_BASE_URL

The generated client resolves the base URL in this order: an explicit base URL passed to the client, an explicit environment passed to the client, the value of the environment variable, then the default environment. base-url-env requires at least one entry under environments; fern check warns (valid-base-url-env) otherwise.

Only the TypeScript SDK generator supports this setting.

URL templating

For APIs deployed across multiple regions or environments, you can define URL templates with variable placeholders that SDK users customize at runtime. To set this up:

1. Define your static base URLs under urls — these appear in the generated environments enum.
2. Add url-templates with {variable} placeholders (e.g., https://api.{region}.example.com/v1) for each service. Fern exposes these as configurable parameters in the SDK.
3. Provide default-urls as concrete fallbacks so SDK users get a working client out of the box without supplying variables.
4. List the available variables for each service, each with an id, a default value, and an optional values list to constrain allowed options.

environments:
  RegionalApiServer:
    urls:
      Base: https://api.example.com/v1
      Auth: https://auth.example.com
    url-templates:
      Base: https://api.{region}.{environment}.example.com/v1
      Auth: https://auth.{region}.example.com
    default-urls:
      Base: https://api.example.com/v1
      Auth: https://auth.example.com
    variables:
      Base:
        - id: region
          default: us-east-1
          values:
            - us-east-1
            - us-west-2
            - eu-west-1
        - id: environment
          default: prod
          values:
            - prod
            - staging
            - dev
      Auth:
        - id: region
          default: us-east-1
          values:
            - us-east-1
            - us-west-2
            - eu-west-1
default-environment: RegionalApiServer

Base path

If you would like all of your endpoints to be prefixed with a path, use base-path.

In the example below, every endpoint is prefixed with a /v1:

name: api
base-path: /v1

Audiences

If you have listed environments that you want to filter, you can leverage audiences.

audiences:
  - public
environments:
  Dev: 
    url: https://api.dev.buildwithfern.com
  Prod: 
    url: https://api.buildwithfern.com
    audiences:
      - external