diff --git a/docs/en/rest-api/migration.asciidoc b/docs/en/rest-api/migration.asciidoc
index 634ebc60102..51f1e5fae0f 100644
--- a/docs/en/rest-api/migration.asciidoc
+++ b/docs/en/rest-api/migration.asciidoc
@@ -6,7 +6,8 @@ The migration APIs simplify upgrading {xpack} indices from one version to anothe
 
 * <<migration-api-assistance>>
 * <<migration-api-upgrade>>
+* <<migration-api-deprecation>>
 
 include::migration/assistance.asciidoc[]
 include::migration/upgrade.asciidoc[]
-
+include::migration/deprecation.asciidoc[]
diff --git a/docs/en/rest-api/migration/deprecation.asciidoc b/docs/en/rest-api/migration/deprecation.asciidoc
new file mode 100644
index 00000000000..6aefb836333
--- /dev/null
+++ b/docs/en/rest-api/migration/deprecation.asciidoc
@@ -0,0 +1,87 @@
+[role="xpack"]
+[[migration-api-deprecation]]
+== Deprecation Info APIs
+
+The deprecation API is to be used to retrieve information about different cluster, node, and index level
+settings that use deprecated features that will be removed or changed in the next major version.
+
+To see the list of offenders in your cluster, submit a GET request to the `_xpack/migration/deprecations` endpoint:
+
+[source,js]
+--------------------------------------------------
+GET /_xpack/migration/deprecations
+--------------------------------------------------
+// CONSOLE
+// TEST[skip:cannot assert tests have certain deprecations]
+
+Example response:
+
+
+[source,js]
+--------------------------------------------------
+{
+  "cluster_settings" : [
+    {
+      "level" : "info",
+      "message" : "Network settings changes",
+      "url" : "https://www.elastic.co/guide/en/elasticsearch/reference/master/breaking_60_indices_changes.html#_index_templates_use_literal_index_patterns_literal_instead_of_literal_template_literal",
+      "details" : "templates using `template` field: watches,.monitoring-alerts,.watch-history-6,.ml-notifications,security-index-template,triggered_watches,.monitoring-es,.ml-meta,.ml-state,.monitoring-logstash,.ml-anomalies-,.monitoring-kibana"
+    }
+  ],
+  "node_settings" : [ ],
+  "index_settings" : {
+    ".monitoring-es-6-2017.07.21" : [
+      {
+        "level" : "info",
+        "message" : "Coercion of boolean fields",
+        "url" : "https://www.elastic.co/guide/en/elasticsearch/reference/master/breaking_60_mappings_changes.html#_coercion_of_boolean_fields",
+        "details" : "[[type: doc, field: spins], [type: doc, field: mlockall], [type: doc, field: node_master], [type: doc, field: primary]]"
+      }
+    ]
+  }
+}
+--------------------------------------------------
+// NOTCONSOLE
+
+The response you will receive will break down all the specific forward-incompatible settings that your
+cluster should resolve before upgrading. Any offending setting will be represented as a deprecation warning.
+
+The following is an example deprecation warning:
+
+[source,js]
+--------------------------------------------------
+{
+  "level" : "info",
+  "message" : "This is the generic descriptive message of the breaking change",
+  "url" : "https://www.elastic.co/guide/en/elasticsearch/reference/master/breaking_60_indices_changes.html",
+  "details" : "more information, like which nodes, indices, or settings are to blame"
+}
+--------------------------------------------------
+// NOTCONSOLE
+
+As is shown, there is a `level` property that describes how significant the issue may be.
+
+|=======
+|none | everything is good
+|info | An advisory note that something has changed. No action needed
+|warning | You can upgrade directly, but you are using deprecated functionality which will not be available in the next major version
+|critical | You cannot upgrade without fixing this problem
+|=======
+
+`message` and the optional `details` provide descriptive information about the deprecation warning, while the `url`
+property provides a link to the Breaking Changes Documentation, where more information about this change can be found.
+
+Any cluster-level deprecation warnings can be found under
+the `cluster_settings` key. Similarly, any node-level warnings will be found under `node_settings`. 
+Since only a select subset of your nodes may incorporate these settings, it is important to read the
+`details` section for more information about which nodes are to be updated. Index warnings are
+sectioned off per index and can be filtered using an index-pattern in the query.
+
+Example request that only shows index-level deprecations of all `logstash-*` indices:
+
+[source,js]
+--------------------------------------------------
+GET /logstash-*/_xpack/migration/deprecations
+--------------------------------------------------
+// CONSOLE
+// TEST[skip:cannot assert tests have certain deprecations]
diff --git a/plugin/src/test/resources/rest-api-spec/api/xpack.deprecation.info.json b/plugin/src/test/resources/rest-api-spec/api/xpack.deprecation.info.json
index 7b5e3956a92..cd4e3cac339 100644
--- a/plugin/src/test/resources/rest-api-spec/api/xpack.deprecation.info.json
+++ b/plugin/src/test/resources/rest-api-spec/api/xpack.deprecation.info.json
@@ -1,6 +1,6 @@
 {
   "xpack.deprecation.info": {
-    "documentation": "http://www.elastic.co/guide/en/migration/current/appendix-api-deprecation-info.html",
+    "documentation": "http://www.elastic.co/guide/en/migration/current/migration-api-deprecation.html",
     "methods": [ "GET" ],
     "url": {
       "path": "/{index}/_xpack/migration/deprecations",