Document usage quota namespaces and scope keys

.generator/schemas/v2/openapi.yaml

@@ -142720,7 +142720,7 @@ components:
       additionalProperties:
         example: jane@example.com
         type: string
-      description: A namespace-specific key and value identifying what the quota applies to within an organization. The object must contain exactly one entry. Use `"*"` as the value for the default quota applied to entities without a specific quota, or omit the scope for an organization-wide quota. A specific value must identify an existing user handle in the caller's organization when `include_descendants` is false. When `include_descendants` is true, the handle must exist in the caller's organization or in at least one targeted descendant organization; the quota is then applied only to the organizations where that handle exists, and the request fails only if the handle exists in none of them.
+      description: A namespace-specific key and value identifying what the quota applies to within an organization. See the endpoint description for the supported scope keys, values, and validation rules.
       example:
         user_handle: jane@example.com
       maxProperties: 1
@@ -142795,7 +142795,7 @@ components:
       additionalProperties:
         example: jane@example.com
         type: string
-      description: A namespace-specific key and value identifying what the quota applies to within an organization. The object contains exactly one entry. A value of `"*"` identifies the default quota applied to entities without a specific quota. This field is omitted for an organization-wide quota.
+      description: A namespace-specific key and value identifying what the quota applies to within an organization. The object contains exactly one entry. A `user_handle` value of `"*"` identifies the default quota applied to users without a specific quota. This field is omitted for an organization-wide quota.
       example:
         user_handle: jane@example.com
       maxProperties: 1
@@ -254413,6 +254413,34 @@ paths:
         For the organization-wide quota, `pending_usage_limit` schedules a limit for the next usage period and can
         accompany an immediate limit or update an existing quota by itself.
         Scheduled changes follow `include_descendants` like the other fields. Requires the `billing_edit` permission.
+
+        ### Quota namespaces and scope keys
+
+        The `quota_namespace` path parameter selects the product whose usage quotas are managed. Each namespace
+        supports its own scope keys, described below. Omit `scope` for the organization-wide quota.
+
+        #### `ai_credits` scope keys
+
+        Each item's `scope` contains exactly one of the following keys.
+
+        **`user_handle`**
+
+        - **Value:** The handle of a user, for example `jane@example.com`, or `"*"` for the default quota applied to
+          users without a specific quota. User handles are returned in the `data[].attributes.handle` field by the
+          [Users API](https://docs.datadoghq.com/api/latest/users/#list-all-users).
+        - **Validation:** A specific handle must identify an existing user in the caller's organization when
+          `include_descendants` is false. When `include_descendants` is true, the handle must exist in the caller's
+          organization or in at least one targeted descendant organization. The quota is then applied only to the
+          organizations where the handle exists, and the item fails only if the handle exists in none of them.
+
+        **`role_uuid`**
+
+        - **Value:** The UUID of a role, for example `12345678-1234-1234-1234-123456789012`. `"*"` is not accepted
+          because there is no default role quota. Role UUIDs are returned in the `data[].id` field by the
+          [Roles API](https://docs.datadoghq.com/api/latest/roles/#list-roles).
+        - **Validation:** The role must exist in the caller's organization. Role UUIDs are unique, so
+          `include_descendants` has no effect on a `role_uuid` scope: the role is validated against the caller's
+          organization only.
       operationId: CreateQuotas
       parameters:
         - description: The product-specific namespace whose usage quotas are being managed.

lib/datadog_api_client/v2/api/usage_metering_api.rb

@@ -39,6 +39,34 @@ def create_quotas(quota_namespace, body, opts = {})
     # accompany an immediate limit or update an existing quota by itself.
     # Scheduled changes follow `include_descendants` like the other fields. Requires the `billing_edit` permission.
     #
+    # ### Quota namespaces and scope keys
+    #
+    # The `quota_namespace` path parameter selects the product whose usage quotas are managed. Each namespace
+    # supports its own scope keys, described below. Omit `scope` for the organization-wide quota.
+    #
+    # #### `ai_credits` scope keys
+    #
+    # Each item's `scope` contains exactly one of the following keys.
+    #
+    # **`user_handle`**
+    #
+    # - **Value:** The handle of a user, for example `jane@example.com`, or `"*"` for the default quota applied to
+    #   users without a specific quota. User handles are returned in the `data[].attributes.handle` field by the
+    #   [Users API](https://docs.datadoghq.com/api/latest/users/#list-all-users).
+    # - **Validation:** A specific handle must identify an existing user in the caller's organization when
+    #   `include_descendants` is false. When `include_descendants` is true, the handle must exist in the caller's
+    #   organization or in at least one targeted descendant organization. The quota is then applied only to the
+    #   organizations where the handle exists, and the item fails only if the handle exists in none of them.
+    #
+    # **`role_uuid`**
+    #
+    # - **Value:** The UUID of a role, for example `12345678-1234-1234-1234-123456789012`. `"*"` is not accepted
+    #   because there is no default role quota. Role UUIDs are returned in the `data[].id` field by the
+    #   [Roles API](https://docs.datadoghq.com/api/latest/roles/#list-roles).
+    # - **Validation:** The role must exist in the caller's organization. Role UUIDs are unique, so
+    #   `include_descendants` has no effect on a `role_uuid` scope: the role is validated against the caller's
+    #   organization only.
+    #
     # @param quota_namespace [String] The product-specific namespace whose usage quotas are being managed.
     # @param body [UsageQuotasCreateRequest] The usage quotas to create or update.
     # @param opts [Hash] the optional parameters

lib/datadog_api_client/v2/models/usage_quota_bulk_result_attributes.rb

@@ -36,7 +36,7 @@ class UsageQuotaBulkResultAttributes
     # The usage limit scheduled for the organization-wide quota in the usage units defined by the quota namespace. A value of `0` is valid. At the start of the effective month, this value becomes `usage_limit` and both pending fields are omitted. Omitted when no change is scheduled or this item failed to write.
     attr_accessor :pending_usage_limit
 
-    # A namespace-specific key and value identifying what the quota applies to within an organization. The object contains exactly one entry. A value of `"*"` identifies the default quota applied to entities without a specific quota. This field is omitted for an organization-wide quota.
+    # A namespace-specific key and value identifying what the quota applies to within an organization. The object contains exactly one entry. A `user_handle` value of `"*"` identifies the default quota applied to users without a specific quota. This field is omitted for an organization-wide quota.
     attr_accessor :scope
 
     # The quota limit in the usage units defined by the quota namespace. May be fractional for quotas configured before public writes required whole units. Omitted if this item failed to write.

lib/datadog_api_client/v2/models/usage_quota_create_attributes.rb

@@ -27,7 +27,7 @@ class UsageQuotaCreateAttributes
     # The non-negative, whole-number limit to schedule for the organization-wide quota in the usage units defined by the quota namespace. It is not checked against current usage. Each write schedules the value for 00:00 UTC on the first day of the next calendar month and replaces any previously scheduled change; the server computes `pending_effective_from`. Omit this field to leave any scheduled change unchanged, including when raising `usage_limit`. Cancel a scheduled change only by deleting the quota's `/pending` sub-resource.
     attr_reader :pending_usage_limit
 
-    # A namespace-specific key and value identifying what the quota applies to within an organization. The object must contain exactly one entry. Use `"*"` as the value for the default quota applied to entities without a specific quota, or omit the scope for an organization-wide quota. A specific value must identify an existing user handle in the caller's organization when `include_descendants` is false. When `include_descendants` is true, the handle must exist in the caller's organization or in at least one targeted descendant organization; the quota is then applied only to the organizations where that handle exists, and the request fails only if the handle exists in none of them.
+    # A namespace-specific key and value identifying what the quota applies to within an organization. See the endpoint description for the supported scope keys, values, and validation rules.
     attr_accessor :scope
 
     # The non-negative, whole-number quota limit to set in the usage units defined by the quota namespace. For an organization-wide quota (scope omitted), the limit must be greater than usage already recorded in the current period. When this field is provided, `enforced` is required.

lib/datadog_api_client/v2/models/usage_quota_response_attributes.rb

@@ -35,7 +35,7 @@ class UsageQuotaResponseAttributes
     # fields are omitted. Omitted when no change is scheduled.
     attr_accessor :pending_usage_limit
 
-    # A namespace-specific key and value identifying what the quota applies to within an organization. The object contains exactly one entry. A value of `"*"` identifies the default quota applied to entities without a specific quota. This field is omitted for an organization-wide quota.
+    # A namespace-specific key and value identifying what the quota applies to within an organization. The object contains exactly one entry. A `user_handle` value of `"*"` identifies the default quota applied to users without a specific quota. This field is omitted for an organization-wide quota.
     attr_accessor :scope
 
     # The quota limit in the usage units defined by the quota namespace. May be fractional for quotas configured before public writes required whole units.