Environments | Fern Documentation

Fern Definition isn’t recommended for new customers and Fern isn’t accepting feature requests for this format. It remains supported for existing users.

You can specify the environments where your server is deployed.

Single URL environments

api.yml

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.

api.yml

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:

auth.yml

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

Default environment

You can also provide a default environment:

api.yml

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

By providing a default environment, the generated SDK will be setup to hit that URL out-of-the-box.

URL templating

URL templating is currently supported for Python and Java SDK generation only.

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:

Define your static base URLs under urls — these appear in the generated environments enum.
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.
Provide default-urls as concrete fallbacks so SDK users get a working client out of the box without supplying variables.
List the available variables for each service, each with an id, a default value, and an optional values list to constrain allowed options.

api.yml

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:

api.yml

name: api
base-path: /v1

Audiences

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

api.yml

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