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

# Environments

> List environments like production, staging, and development.

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`**

```yaml title="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`**

```yaml title="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`**

```yaml title="auth.yml"
service:
  url: Auth
  base-path: /auth
  ...
```

## Default environment

You can also provide a default environment:

**`api.yml`**

```yaml title="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:

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.

**`api.yml`**

```yaml title="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`**

```yaml title="api.yml"
name: api
base-path: /v1
```

## Audiences

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

**`api.yml`**

```yaml title="api.yml"
audiences:
  - public

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

> List environments like production, staging, and development.