Availability

The x-fern-availability extension marks the availability of an endpoint within your OpenAPI definition. The availability information propagates into the generated Fern Docs website as visual tags, SDKs, and CLIs.

Endpoint

Set x-fern-availability on an endpoint to one of the following values:

The example below marks that the POST /pet endpoint is deprecated.

1
paths:
2
  /pet:
3
    post:
4
      x-fern-availability: deprecated

API Reference output

The endpoint renders with the corresponding tag in your API Reference docs.

SDK output

Availability values propagate into generated SDKs as doc comments on client methods (JSDoc in TypeScript, docstrings in Python, Javadoc in Java, etc.). IDEs surface these as warnings and strikethrough styling so SDK users see at a glance which endpoints to avoid.

1
export class PetClient {
2
    /** @deprecated */
3
    public addPet( ... ): Promise<Pet> { ... }
4
5
    /** @beta This endpoint is in pre-release and may change. */
6
    public getPetById( ... ): Promise<Pet> { ... }
7
}

To attach a custom message, write x-fern-availability as an object with status and message fields:

1
paths:
2
  /pet:
3
    put:
4
      x-fern-availability:
5
        status: deprecated
6
        message: Use PATCH /pet instead.

Section

You can set the availability for the entire API reference or for specific sections in your docs.yml configuration. Options are: stable, generally-available, in-development, pre-release, deprecated, alpha, beta, preview, or legacy.

When you set the availability of a section, all of the endpoints in that section are automatically marked with that availability unless explicitly set otherwise.

1
navigation: 
2
  - api: API Reference
3
    availability: generally-available
4
    layout: 
5
      - section: My Section
6
        availability: beta
7
        icon: flower
8
        contents: 
9
        # endpoints here