fern-api · fern-api · May 15, 2026 · May 15, 2026 · May 15, 2026 · May 15, 2026
@@ -78,8 +78,6 @@ products:
     image: ./images/product-switcher/openapi-definition-light.png
     slug: api-definitions
     subtitle: Import and configure your API specifications
-    announcement:
-      message: '<a href="/learn/api-definitions/ferndef/overview">Fern Definition</a> is no longer actively recommended for new projects but remains supported for existing users.'
 
   - display-name: OpenAPI
     href: /learn/api-definitions/openapi/overview

@@ -4,6 +4,8 @@ description: List environments like production, staging, and development.
 noindex: true
 ---
 
+<Markdown src="/products/api-def/snippets/ferndef-deprecation.mdx" />
+
 
 You can specify the environments where your server is deployed. 
 

@@ -4,6 +4,8 @@ description: Specify error types and schemas
 noindex: true
 ---
 
+<Markdown src="/products/api-def/snippets/ferndef-deprecation.mdx" />
+
 
 In order to generate SDKs idiomatically, Fern needs to know how to differentiate
 between different errors when parsing an endpoint response.

@@ -4,6 +4,8 @@ description: Specify global headers, path parameters or query parameters meant t
 noindex: true
 ---
 
+<Markdown src="/products/api-def/snippets/ferndef-deprecation.mdx" />
+
 
 The `api.yml` configuration supports global configuration like headers and path parameters. 
 

@@ -4,6 +4,8 @@ description: The api.yml file contains general API configuration when using the
 noindex: true
 ---
 
+<Markdown src="/products/api-def/snippets/ferndef-deprecation.mdx" />
+
 
 A `fern/` folder has a special file called `api.yml`, which includes all the API-wide configuration.
 

@@ -4,6 +4,8 @@ subtitle: Use audiences in your Fern Definition to segment your API for differen
 noindex: true
 ---
 
+<Markdown src="/products/api-def/snippets/ferndef-deprecation.mdx" />
+
 
 <Markdown src="/snippets/team-or-pro-plan.mdx"/>
 

@@ -4,6 +4,8 @@ description: Configure API authentication in Fern Definition. Set up bearer toke
 noindex: true
 ---
 
+<Markdown src="/products/api-def/snippets/ferndef-deprecation.mdx" />
+
 
 Configuring authentication schemes happens in the `api.yml` file. All Fern-generated SDKs support both direct configuration and environment variables for authentication credentials.
 

@@ -4,6 +4,8 @@ description: Add availability to Fern Definition API services, endpoints, types,
 noindex: true
 ---
 
+<Markdown src="/products/api-def/snippets/ferndef-deprecation.mdx" />
+
 
 You can add `availability` to an endpoint, type, or property within your Fern Definition. You can configure the `availability` of sections in your API Reference documentation in your [`docs.yml` file](/learn/docs/configuration/site-level-settings). 
 

@@ -4,6 +4,8 @@ subtitle: Import API Definitions to generate unified SDKs
 noindex: true
 ---
 
+<Markdown src="/products/api-def/snippets/ferndef-deprecation.mdx" />
+
 
 Fern allows you to import other APIs into your API.
 

@@ -4,6 +4,8 @@ description: Organize related API endpoints into a service in Fern Definition an
 noindex: true
 ---
 
+<Markdown src="/products/api-def/snippets/ferndef-deprecation.mdx" />
+
 
 In Fern, you organize related endpoints into a **Service**. This grouping
 improves clarity and makes the generated SDKs more idiomatic.

@@ -4,6 +4,8 @@ subtitle: Use the `bytes` type to handle binary data in your API
 noindex: true
 ---
 
+<Markdown src="/products/api-def/snippets/ferndef-deprecation.mdx" />
+
 
 <Note>
   The `bytes` type allows you to handle binary data in both requests and responses.

@@ -4,6 +4,8 @@ description: Document endpoints with the `multiform` content type.
 noindex: true
 ---
 
+<Markdown src="/products/api-def/snippets/ferndef-deprecation.mdx" />
+
 
 Endpoints in Fern are defined underneath the `endpoints` key. If your endpoint request includes file uploads, you can use the `file` type to indicate the request is of a `multiform` content type. The example below demonstrates an endpoint which includes a file in the request body. 
 

@@ -4,6 +4,8 @@ noindex: true
 description: "Define HTTP JSON endpoints in the Fern Definition under the endpoints key, including path, method, request bodies, responses, and examples."
 ---
 
+<Markdown src="/products/api-def/snippets/ferndef-deprecation.mdx" />
+
 
 Endpoints in Fern are defined underneath the `endpoints` key. Below is an example of defining 
 a single REST endpoint: 

@@ -4,6 +4,8 @@ subtitle: Use the `response-stream` key to model streaming endpoints
 noindex: true
 ---
 
+<Markdown src="/products/api-def/snippets/ferndef-deprecation.mdx" />
+
 
 <Markdown src="/snippets/team-or-pro-plan.mdx"/>
 

@@ -4,6 +4,8 @@ description: Add errors representing failed responses from API endpoints in Fern
 noindex: true
 ---
 
+<Markdown src="/products/api-def/snippets/ferndef-deprecation.mdx" />
+
 
 Errors represent failed (non-200) responses from endpoints.
 

@@ -4,6 +4,8 @@ subtitle: Use Fern Definition to add API examples that are shown in comments of
 noindex: true
 ---
 
+<Markdown src="/products/api-def/snippets/ferndef-deprecation.mdx" />
+
 
 You can add examples for types and endpoints. Examples are shown as
 comments in your SDKs, in the request & response of your documentation,

@@ -4,6 +4,8 @@ description: Export Fern Definition to OpenAPI 3.1 format using the fern export
 noindex: true
 ---
 
+<Markdown src="/products/api-def/snippets/ferndef-deprecation.mdx" />
+
 
 To prevent lock-in to the Fern Definition format, you can export your API definition to OpenAPI 3.1 at any time [using the `fern export` command](/cli-api-reference/cli-reference/commands#fern-export). 
 

@@ -4,6 +4,8 @@ description: Use imports to reference API types and errors from other Fern Defin
 noindex: true
 ---
 
+<Markdown src="/products/api-def/snippets/ferndef-deprecation.mdx" />
+
 
 Imports allow you to reference types and errors from other files.
 

@@ -4,6 +4,8 @@ description: Fern Definition is a YAML format for API specifications. Define you
 noindex: true
 ---
 
+<Markdown src="/products/api-def/snippets/ferndef-deprecation.mdx" />
+
 
 A Fern Definition is a set of YAML files that are the single source of truth for your API. You check your Fern Definition into your repo,
 inside of which describes your API requests, responses, models, paths, methods, errors, and authentication scheme.

@@ -4,6 +4,8 @@ description: Fern Definition enables the reuse of API type and error names acros
 noindex: true
 ---
 
+<Markdown src="/products/api-def/snippets/ferndef-deprecation.mdx" />
+
 
 ## What is a package?
 

@@ -4,6 +4,8 @@ description: Types describe the data model of your API. Fern has many built-in t
 noindex: true
 ---
 
+<Markdown src="/products/api-def/snippets/ferndef-deprecation.mdx" />
+
 
 Types describe the data model of your API.
 

@@ -5,6 +5,8 @@ max-toc-depth: 3
 noindex: true
 ---
 
+<Markdown src="/products/api-def/snippets/ferndef-deprecation.mdx" />
+
 
 In Fern, you can specify webhooks in your API definition. The webhooks will be included 
 in both the generated SDKs and the API documentation.

@@ -4,6 +4,8 @@ description: Learn how to define WebSockets in the Fern Definition
 noindex: true
 ---
 
+<Markdown src="/products/api-def/snippets/ferndef-deprecation.mdx" />
+
 
 WebSockets enable a user to create a connection with a server, over which bidirectional communication can be sent. 
 

diff --git a/fern/products/api-def/snippets/ferndef-deprecation.mdx b/fern/products/api-def/snippets/ferndef-deprecation.mdx
@@ -0,0 +1,3 @@
+<Note title="Fern Definition is no longer recommended">
+Fern Definition is not recommended for new customers. We are not actively developing new features or accepting feature requests for this format. If you're starting a new project, we recommend using [OpenAPI](/learn/api-definitions/openapi/overview) instead.
+</Note>
-Original file line number
+Diff line change
@@ Expand Up @@
     noindex: true
     ---
+    <Markdown src="/products/api-def/snippets/ferndef-deprecation.mdx" />
     You can specify the environments where your server is deployed.
@@ Expand Down @@