diff --git a/.generator/schemas/v2/openapi.yaml b/.generator/schemas/v2/openapi.yaml
index cd024ee16898..ab889acf9f77 100644
--- a/.generator/schemas/v2/openapi.yaml
+++ b/.generator/schemas/v2/openapi.yaml
@@ -117110,7 +117110,10 @@ components:
       description: Request to create or update a targeting rule (allocation) for a feature flag environment.
       properties:
         experiment_id:
-          description: The experiment ID for experiment-linked allocations.
+          description: |-
+            The experiment ID linked to the allocation. For `FEATURE_GATE` allocations,
+            a non-null value denotes a standard experiment. For `CANARY` allocations,
+            Datadog manages this value. Omit it when creating a canary allocation.
           example: "550e8400-e29b-41d4-a716-446655440030"
           nullable: true
           type: string
@@ -144699,6 +144702,11 @@ paths:
       description: |-
         Updates targeting rules (allocations) for a specific feature flag in a specific environment.
         This operation replaces the existing allocation set with the request payload.
+        Creating, updating, or deleting a standard experiment allocation—an allocation with
+        `type: FEATURE_GATE` and a non-null `experiment_id`—also requires the
+        `product_analytics_experiments_write` permission. This additional permission is not
+        required for `CANARY` allocations, exposure schedules, or guardrail metrics unless
+        the same operation also mutates a standard experiment allocation.
       operationId: UpdateAllocationsForFeatureFlagInEnvironment
       parameters:
         - $ref: "#/components/parameters/feature_flag_id"
@@ -144772,7 +144780,9 @@ paths:
             application/json:
               schema:
                 $ref: "#/components/schemas/APIErrorResponse"
-          description: Forbidden
+          description: |-
+            Forbidden. The caller is missing the `feature_flag_config_write` permission.
+            This error is also returned when the operation mutates a standard experiment allocation and the caller is missing the `product_analytics_experiments_write` permission.
         "404":
           content:
             application/json:
diff --git a/lib/datadog_api_client/v2/api/feature_flags_api.rb b/lib/datadog_api_client/v2/api/feature_flags_api.rb
index a048eec828c1..2cfb15020558 100644
--- a/lib/datadog_api_client/v2/api/feature_flags_api.rb
+++ b/lib/datadog_api_client/v2/api/feature_flags_api.rb
@@ -1282,6 +1282,11 @@ def update_allocations_for_feature_flag_in_environment(feature_flag_id, environm
     #
     # Updates targeting rules (allocations) for a specific feature flag in a specific environment.
     # This operation replaces the existing allocation set with the request payload.
+    # Creating, updating, or deleting a standard experiment allocation—an allocation with
+    # `type: FEATURE_GATE` and a non-null `experiment_id`—also requires the
+    # `product_analytics_experiments_write` permission. This additional permission is not
+    # required for `CANARY` allocations, exposure schedules, or guardrail metrics unless
+    # the same operation also mutates a standard experiment allocation.
     #
     # @param feature_flag_id [UUID] The ID of the feature flag.
     # @param environment_id [UUID] The ID of the environment.
diff --git a/lib/datadog_api_client/v2/models/upsert_allocation_request.rb b/lib/datadog_api_client/v2/models/upsert_allocation_request.rb
index 4f19f60d283f..de4a5bcccebb 100644
--- a/lib/datadog_api_client/v2/models/upsert_allocation_request.rb
+++ b/lib/datadog_api_client/v2/models/upsert_allocation_request.rb
@@ -21,7 +21,9 @@ module DatadogAPIClient::V2
   class UpsertAllocationRequest
     include BaseGenericModel
 
-    # The experiment ID for experiment-linked allocations.
+    # The experiment ID linked to the allocation. For `FEATURE_GATE` allocations,
+    # a non-null value denotes a standard experiment. For `CANARY` allocations,
+    # Datadog manages this value. Omit it when creating a canary allocation.
     attr_accessor :experiment_id
 
     # Progressive release request payload.