Document usage quota namespaces and scope keys

.generator/schemas/v2/openapi.yaml

@@ -142769,7 +142769,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
@@ -142844,7 +142844,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
@@ -254501,6 +254501,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.

src/main/java/com/datadog/api/client/v2/api/UsageMeteringApi.java

@@ -179,6 +179,44 @@ public CompletableFuture<UsageQuotasBulkResponse> createQuotasAsync(
    * update an existing quota by itself. Scheduled changes follow <code>include_descendants</code>
    * like the other fields. Requires the <code>billing_edit</code> permission.
    *
+   * <h3>Quota namespaces and scope keys</h3>
+   *
+   * <p>The <code>quota_namespace</code> path parameter selects the product whose usage quotas are
+   * managed. Each namespace supports its own scope keys, described below. Omit <code>scope</code>
+   * for the organization-wide quota.
+   *
+   * <h3><code>ai_credits</code> scope keys</h3>
+   *
+   * <p>Each item's <code>scope</code> contains exactly one of the following keys.
+   *
+   * <p><strong><code>user_handle</code></strong>
+   *
+   * <ul>
+   *   <li><strong>Value:</strong> The handle of a user, for example <code>jane@example.com</code>,
+   *       or <code>"*"</code> for the default quota applied to users without a specific quota. User
+   *       handles are returned in the <code>data[].attributes.handle</code> field by the <a
+   *       href="https://docs.datadoghq.com/api/latest/users/#list-all-users">Users API</a>.
+   *   <li><strong>Validation:</strong> A specific handle must identify an existing user in the
+   *       caller's organization when <code>include_descendants</code> is false. When <code>
+   *       include_descendants</code> 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.
+   * </ul>
+   *
+   * <p><strong><code>role_uuid</code></strong>
+   *
+   * <ul>
+   *   <li><strong>Value:</strong> The UUID of a role, for example <code>
+   *       12345678-1234-1234-1234-123456789012</code>. <code>"*"</code> is not accepted because
+   *       there is no default role quota. Role UUIDs are returned in the <code>data[].id</code>
+   *       field by the <a href="https://docs.datadoghq.com/api/latest/roles/#list-roles">Roles
+   *       API</a>.
+   *   <li><strong>Validation:</strong> The role must exist in the caller's organization. Role UUIDs
+   *       are unique, so <code>include_descendants</code> has no effect on a <code>role_uuid</code>
+   *       scope: the role is validated against the caller's organization only.
+   * </ul>
+   *
    * @param quotaNamespace The product-specific namespace whose usage quotas are being managed.
    *     (required)
    * @param body The usage quotas to create or update. (required)

src/main/java/com/datadog/api/client/v2/model/UsageQuotaBulkResultAttributes.java

@@ -182,9 +182,9 @@ public UsageQuotaBulkResultAttributes putScopeItem(String key, String scopeItem)
 
   /**
    * A namespace-specific key and value identifying what the quota applies to within an
-   * organization. The object contains exactly one entry. A value of <code>"*"</code> identifies the
-   * default quota applied to entities without a specific quota. This field is omitted for an
-   * organization-wide quota.
+   * organization. The object contains exactly one entry. A <code>user_handle</code> value of <code>
+   * "*"</code> identifies the default quota applied to users without a specific quota. This field
+   * is omitted for an organization-wide quota.
    *
    * @return scope
    */

src/main/java/com/datadog/api/client/v2/model/UsageQuotaCreateAttributes.java

@@ -109,13 +109,8 @@ public UsageQuotaCreateAttributes putScopeItem(String key, String scopeItem) {
 
   /**
    * A namespace-specific key and value identifying what the quota applies to within an
-   * organization. The object must contain exactly one entry. Use <code>"*"</code> 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 <code>include_descendants</code> is false. When <code>include_descendants
-   * </code> 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.
+   * organization. See the endpoint description for the supported scope keys, values, and validation
+   * rules.
    *
    * @return scope
    */

src/main/java/com/datadog/api/client/v2/model/UsageQuotaResponseAttributes.java

@@ -162,9 +162,9 @@ public UsageQuotaResponseAttributes putScopeItem(String key, String scopeItem) {
 
   /**
    * A namespace-specific key and value identifying what the quota applies to within an
-   * organization. The object contains exactly one entry. A value of <code>"*"</code> identifies the
-   * default quota applied to entities without a specific quota. This field is omitted for an
-   * organization-wide quota.
+   * organization. The object contains exactly one entry. A <code>user_handle</code> value of <code>
+   * "*"</code> identifies the default quota applied to users without a specific quota. This field
+   * is omitted for an organization-wide quota.
    *
    * @return scope
    */