diff --git a/docs/reference/api-conventions.asciidoc b/docs/reference/api-conventions.asciidoc
index 66d2bbd77fcc7..a9989460098ce 100644
--- a/docs/reference/api-conventions.asciidoc
+++ b/docs/reference/api-conventions.asciidoc
@@ -11,6 +11,37 @@ Alternatively, you can pass the request body as the
 <<api-request-body-query-string, `source` query string parameter>>
 when using GET.
 
+[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
+----------------------------------------------------------------------
+
 * <<multi-index>>
 * <<date-math-index-names>>
 * <<cron-expressions>>