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

# Availability

> Mark API endpoint availability in OpenAPI with `x-fern-availability`. Set beta, deprecated, stable, etc. statuses for endpoints and sections.

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, TypeScript SDKs, and [CLIs](/learn/cli-generator/get-started/openapi-extensions#availability-badges).

## Endpoint

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

| Value                 | Description                            | Tag          |
| --------------------- | -------------------------------------- | ------------ |
| `alpha`               | Early experimental stage               | `Alpha`      |
| `beta`                | Stable enough for early adopters       | `Beta`       |
| `preview`             | Feature-complete but subject to change | `Preview`    |
| `generally-available` | Stable and ready for production        | `GA`         |
| `deprecated`          | No longer recommended for new use      | `Deprecated` |
| `legacy`              | Superseded but still supported         | `Legacy`     |

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

**`x-fern-availability in openapi.yml`**

```yaml title="x-fern-availability in openapi.yml" {4}
paths:
  /pet:
    post:
      x-fern-availability: deprecated
```

### API Reference output

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

![Screenshot of API Reference endpoint with tag showing deprecated](https://fern-image-hosting.s3.amazonaws.com/fern/x-fern-availability-example.png)

### SDK output

The TypeScript SDK generator adds JSDoc availability tags to endpoint client methods. Deprecated endpoints receive `@deprecated`; `alpha`, `beta`, and `preview` endpoints receive `@beta`. IDEs can display deprecated methods with warnings and strikethrough styling.

Other SDK generators don't emit availability annotations. Availability on types, properties, and enum values also doesn't add annotations to generated code.

**`Generated TypeScript SDK`**

```typescript title="Generated TypeScript SDK"
export class PetClient {
    /** @deprecated */
    public addPet( ... ): Promise<Pet> { ... }

    /** @beta This endpoint is in pre-release and may change. */
    public getPetById( ... ): Promise<Pet> { ... }
}
```

![Deprecated method with strikethrough and @deprecated tag in VS Code](/learn/_fern-img/e8a1138bbd666260fc8f14cea5e8159a8fdf872c4d5a9869e1897c97623ef690.webp)

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

**`openapi.yml`**

```yaml title="openapi.yml" {4-6}
paths:
  /pet:
    put:
      x-fern-availability:
        status: deprecated
        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.

**`docs.yml`**

```yaml title="docs.yml" {3, 6}
navigation: 
  - api: API Reference
    availability: generally-available
    layout: 
      - section: My Section
        availability: beta
        icon: flower
        contents: 
        # endpoints here
```

> Mark API endpoint availability in OpenAPI with `x-fern-availability`. Set beta, deprecated, stable, etc. statuses for endpoints and sections.