diff --git a/placement-api-ref/source/inventories.inc b/placement-api-ref/source/inventories.inc
index cfbba286e7..4d5eb2bac1 100644
--- a/placement-api-ref/source/inventories.inc
+++ b/placement-api-ref/source/inventories.inc
@@ -115,6 +115,12 @@ Normal Response Codes: 204
 
 Error response codes: itemNotFound(404), conflict(409)
 
+.. note:: Since this request does not accept the resource provider generation,
+          it is not safe to use when multiple threads are managing inventories
+          for a single provider.  In such situations, use the
+          ``PUT /resource_providers/{uuid}/inventories`` API with an empty
+          ``inventories`` dict.
+
 Request
 -------
 
diff --git a/placement-api-ref/source/resource_provider_traits.inc b/placement-api-ref/source/resource_provider_traits.inc
index 74bb20c4b6..73a491ac82 100644
--- a/placement-api-ref/source/resource_provider_traits.inc
+++ b/placement-api-ref/source/resource_provider_traits.inc
@@ -102,6 +102,12 @@ Error response codes: itemNotFound(404), conflict(409)
 * `409 Conflict` if the provider's traits are updated by another
   thread while attempting the operation.
 
+.. note:: Since this request does not accept the resource provider generation,
+          it is not safe to use when multiple threads are managing traits for
+          a single provider.  In such situations, use the
+          ``PUT /resource_providers/{uuid}/traits`` API with an empty
+          ``traits`` list.
+
 Request
 -------