diff --git a/docs/reference/api-conventions.asciidoc b/docs/reference/api-conventions.asciidoc
index 304181792cb4f..71b60f9e3d402 100644
--- a/docs/reference/api-conventions.asciidoc
+++ b/docs/reference/api-conventions.asciidoc
@@ -214,6 +214,37 @@ instead. When using this method, the `source_content_type` parameter
 should also be passed with a media type value that indicates the format
 of the source, such as `application/json`.
 
+[discrete]
+[[api-compatibility]]
+=== REST API version compatibility
+
+Major version upgrades often include a number of breaking changes 
+that impact how you interact with {es}. 
+While we recommend that you monitor the deprecation logs and 
+update applications before upgrading {es},
+having to coordinate the necessary changes can be an impediment to upgrading. 
+
+You can enable an existing application to function without modification after
+an upgrade by including API compatibility headers, which tell {es} you are still
+using the previous version of the REST API. Using these headers allows the 
+structure of requests and responses to remain the same; it does not guarantee
+the same behavior. 
+
+
+You set version compatibility on a per-request basis in the `Content-Type` and `Accept` headers. 
+Setting `compatible-with` to the same major version as 
+the version you're running has no impact, 
+but ensures that the request will still work after {es} is upgraded. 
+
+To tell {es} 8.0 you are using the 7.x request and response format, 
+set `compatible-with=7`:
+
+[source,sh]
+----------------------------------------------------------------------
+Content-Type: application/vnd.elasticsearch+json; compatible-with=7
+Accept: application/vnd.elasticsearch+json; compatible-with=7
+----------------------------------------------------------------------
+
 [discrete]
 [[api-url-access-control]]
 === URL-based access control