diff --git a/docs/reference/migration/migrate_7_0/api.asciidoc b/docs/reference/migration/migrate_7_0/api.asciidoc
index 2da822a7e5e62..fc037504c5128 100644
--- a/docs/reference/migration/migrate_7_0/api.asciidoc
+++ b/docs/reference/migration/migrate_7_0/api.asciidoc
@@ -22,6 +22,32 @@ The following parameters starting with underscore have been removed:
 Instead of these removed parameters, use their non camel case equivalents without
 starting underscore, e.g. use `version_type` instead of `_version_type` or `versionType`.
 
+==== Thread pool info
+
+In previous versions of Elasticsearch, the thread pool info returned in the
+<<cluster-nodes-info,nodes info API>> returned `min` and `max` values reflecting
+the configured minimum and maximum number of threads that could be in each
+thread pool. The trouble with this representation is that it does not align with
+the configuration parameters used to configure thread pools. For
+<<modules-threadpool,scaling thread pools>>, the minimum number of threads is
+configured by a parameter called `core` and the maximum number of threads is
+configured by a parameter called `max`. For <<modules-threadpool,fixed thread
+pools>>, there is only one configuration parameter along these lines and that
+parameter is called `size`, reflecting the fixed number of threads in the
+pool. This discrepancy between the API and the configuration parameters has been
+rectified. Now, the API will report `core` and `max` for scaling thread pools,
+and `size` for fixed thread pools.
+
+Similarly, in the cat thread pool API the existing `size` output has been
+renamed to `pool_size` which reflects the number of threads currently in the
+pool; the shortcut for this value has been changed from `s` to `psz`.  The `min`
+output has been renamed to `core` with a shortcut of `cr`, the shortcut for
+`max` has been changed to `mx`, and the `size` output with a shortcut of `sz`
+has been reused to report the configured number of threads in the pool.  This
+aligns the output of the API with the configuration values for thread
+pools. Note that `core` and `max` will be populated for scaling thread pools,
+and `size` will be populated for fixed thread pools.
+
 ==== The parameter `fields` deprecated in 6.x has been removed from Bulk request 
 and Update request. The Update API returns `400 - Bad request` if request contains 
 unknown parameters (instead of ignored in the previous version).