From a26fba8c92b508d2832c9229fbfc4767b07aeb7d Mon Sep 17 00:00:00 2001 From: Niels Swimberghe <3382717+Swimburger@users.noreply.github.com> Date: Thu, 23 Apr 2026 23:20:55 +0000 Subject: [PATCH 1/4] docs: add alpha, preview, legacy availability values Document the newly supported x-fern-availability / availability values for OpenAPI endpoints and Fern Definitions: alpha, preview, legacy. Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com> --- fern/products/api-def/ferndef/availability.mdx | 5 ++++- .../products/api-def/openapi/extensions/availability.mdx | 9 ++++++--- 2 files changed, 10 insertions(+), 4 deletions(-) diff --git a/fern/products/api-def/ferndef/availability.mdx b/fern/products/api-def/ferndef/availability.mdx index 4baf5f751..2f10ab68d 100644 --- a/fern/products/api-def/ferndef/availability.mdx +++ b/fern/products/api-def/ferndef/availability.mdx @@ -9,10 +9,13 @@ You can add `availability` to an endpoint, type, or property within your Fern De ## Endpoints, types, and properties Availability can be: +- `alpha` which means it is an early experimental release; will show an `Alpha` tag - `in-development` which means it is being worked on; will show a `Beta` tag - `pre-release` which means it is available; will show a `Beta` tag -- `deprecated` which means it will be removed in the future; will show a `Deprecated` tag +- `preview` which means it is feature-complete but subject to change; will show a `Preview` tag - `generally-available` which means it is stable and available for use; will show a `GA` tag +- `deprecated` which means it will be removed in the future; will show a `Deprecated` tag +- `legacy` which means it has been superseded but is still supported; will show a `Legacy` tag ### Endpoint diff --git a/fern/products/api-def/openapi/extensions/availability.mdx b/fern/products/api-def/openapi/extensions/availability.mdx index ecda74e81..355ea3d3b 100644 --- a/fern/products/api-def/openapi/extensions/availability.mdx +++ b/fern/products/api-def/openapi/extensions/availability.mdx @@ -13,9 +13,12 @@ You can configure the `availability` of sections in your API Reference documenta The options are: -- `beta` -- `generally-available` -- `deprecated` +- `alpha` — early experimental stage; shows an `Alpha` tag +- `beta` — stable enough for early adopters; shows a `Beta` tag +- `preview` — feature-complete but subject to change; shows a `Preview` tag +- `generally-available` — stable and ready for production; shows a `GA` tag +- `deprecated` — no longer recommended for new use; shows a `Deprecated` tag +- `legacy` — superseded but still supported; shows a `Legacy` tag The example below marks that the `POST /pet` endpoint is `deprecated`. From 9ea15dc00e4a373fb3fab710227036584f760a4c Mon Sep 17 00:00:00 2001 From: Devin Logan Date: Thu, 23 Apr 2026 20:08:51 -0400 Subject: [PATCH 2/4] list --> markdown table --- fern/products/api-def/ferndef/availability.mdx | 17 ++++++++++------- .../api-def/openapi/extensions/availability.mdx | 14 ++++++++------ 2 files changed, 18 insertions(+), 13 deletions(-) diff --git a/fern/products/api-def/ferndef/availability.mdx b/fern/products/api-def/ferndef/availability.mdx index 2f10ab68d..885d2ed50 100644 --- a/fern/products/api-def/ferndef/availability.mdx +++ b/fern/products/api-def/ferndef/availability.mdx @@ -9,13 +9,16 @@ You can add `availability` to an endpoint, type, or property within your Fern De ## Endpoints, types, and properties Availability can be: -- `alpha` which means it is an early experimental release; will show an `Alpha` tag -- `in-development` which means it is being worked on; will show a `Beta` tag -- `pre-release` which means it is available; will show a `Beta` tag -- `preview` which means it is feature-complete but subject to change; will show a `Preview` tag -- `generally-available` which means it is stable and available for use; will show a `GA` tag -- `deprecated` which means it will be removed in the future; will show a `Deprecated` tag -- `legacy` which means it has been superseded but is still supported; will show a `Legacy` tag + +| Value | Description | Tag | +| --- | --- | --- | +| `alpha` | Early experimental release | `Alpha` | +| `in-development` | Being worked on | `Beta` | +| `pre-release` | Available | `Beta` | +| `preview` | Feature-complete but subject to change | `Preview` | +| `generally-available` | Stable and available for use | `GA` | +| `deprecated` | Will be removed in the future | `Deprecated` | +| `legacy` | Superseded but still supported | `Legacy` | ### Endpoint diff --git a/fern/products/api-def/openapi/extensions/availability.mdx b/fern/products/api-def/openapi/extensions/availability.mdx index 355ea3d3b..362281593 100644 --- a/fern/products/api-def/openapi/extensions/availability.mdx +++ b/fern/products/api-def/openapi/extensions/availability.mdx @@ -13,12 +13,14 @@ You can configure the `availability` of sections in your API Reference documenta The options are: -- `alpha` — early experimental stage; shows an `Alpha` tag -- `beta` — stable enough for early adopters; shows a `Beta` tag -- `preview` — feature-complete but subject to change; shows a `Preview` tag -- `generally-available` — stable and ready for production; shows a `GA` tag -- `deprecated` — no longer recommended for new use; shows a `Deprecated` tag -- `legacy` — superseded but still supported; shows a `Legacy` tag +| 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`. From 12198e43b9e4dcd084b30c5a1922d3c15bef85fb Mon Sep 17 00:00:00 2001 From: Niels Swimberghe <3382717+Swimburger@users.noreply.github.com> Date: Sat, 25 Apr 2026 00:06:07 +0000 Subject: [PATCH 3/4] docs: add beta to fern definition availability table Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com> --- fern/products/api-def/ferndef/availability.mdx | 1 + 1 file changed, 1 insertion(+) diff --git a/fern/products/api-def/ferndef/availability.mdx b/fern/products/api-def/ferndef/availability.mdx index 885d2ed50..031ae99a4 100644 --- a/fern/products/api-def/ferndef/availability.mdx +++ b/fern/products/api-def/ferndef/availability.mdx @@ -14,6 +14,7 @@ Availability can be: | --- | --- | --- | | `alpha` | Early experimental release | `Alpha` | | `in-development` | Being worked on | `Beta` | +| `beta` | Available but may change | `Beta` | | `pre-release` | Available | `Beta` | | `preview` | Feature-complete but subject to change | `Preview` | | `generally-available` | Stable and available for use | `GA` | From a6cbe443c15172dc31bc5c5ae7941425494931fa Mon Sep 17 00:00:00 2001 From: Niels Swimberghe <3382717+Swimburger@users.noreply.github.com> Date: Sat, 25 Apr 2026 00:18:59 +0000 Subject: [PATCH 4/4] docs: include alpha, preview, legacy in shared availability snippet Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com> --- fern/products/api-def/snippets/availability.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/fern/products/api-def/snippets/availability.mdx b/fern/products/api-def/snippets/availability.mdx index 86d143909..69191e0fa 100644 --- a/fern/products/api-def/snippets/availability.mdx +++ b/fern/products/api-def/snippets/availability.mdx @@ -1,4 +1,4 @@ -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`, or `beta`. +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.