zuplo 7.6.3 → 7.6.5

package/docs/ai-gateway/getting-started.mdx

@@ -98,17 +98,17 @@ account, Zuplo project, and AI Gateway team roles control access.
 
 4. **Create a team**
 
-   Teams organize users and carry hierarchical budget controls and policy
-   templates. Even if you're starting solo, you need at least one team.
+   Teams organize users and carry their own budget rules and policy templates.
+   Even if you're starting solo, you need at least one team.
 
    Open the **Apps & Teams** tab and click **New Team**. Name your team (for
    example, "Root" or your company name), choose an icon, and click **Create
    Team**. This is your first team, so there's no parent picker yet—it appears
    on later teams, letting you nest them. To set gateway-wide spending limits
-   across this Zuplo project, open the gateway's **Settings → Usage Limits**;
-   for team-specific limits, use the team's **Usage & Limits** tab. See
-   [Usage Limits](./usage-limits.mdx). Gateway and team limits apply to every
-   app regardless of its policy chain.
+   across this Zuplo project, open the gateway's **Settings → Usage Limits**.
+   Team budgets—shared and per-expression—are set on the team's **Usage &
+   Limits** tab. See [Usage Limits](./usage-limits.mdx). Gateway and team limits
+   apply to every app regardless of its policy chain.
 
 5. **Create an app**
 

package/docs/ai-gateway/managing-apps.mdx

@@ -86,10 +86,11 @@ over—see [Dynamic model routing](./cookbooks/dynamic-model-routing.mdx).
 ## Setting budgets
 
 App budgets live on the **Budgets and Costs** policy in the app's chain. Open
-the app's **Policies** tab and configure it with daily or monthly limits for
-spending, tokens, or requests. Team and gateway limits apply to every app
-automatically, even when the app's chain doesn't include Budgets and Costs. See
-[Usage Limits](./usage-limits.mdx).
+the app's **Policies** tab and add budget rules capping spending, tokens, or
+requests over an hourly, daily, weekly, or monthly period—either for the app as
+a whole or per metadata value, so each caller gets its own budget. Team and
+gateway limits apply to every app automatically, even when the app's chain
+doesn't include Budgets and Costs. See [Usage Limits](./usage-limits.mdx).
 
 ## Editing an App
 

package/docs/ai-gateway/managing-teams.mdx

@@ -39,10 +39,11 @@ click **Create Sub-Team** in the team's header.
 
 After creating a team, use its tabs to configure it:
 
-- **Policies**—the team's [policy template](./policy-templates.mdx), the
+- **Policy Template**—the team's [policy template](./policy-templates.mdx), the
   starting policy chain for apps created in the team.
-- **Usage & Limits**—spending limits that apply to all of the team's apps
-  combined. See [Usage Limits](./usage-limits.mdx).
+- **Usage & Limits**—the team's budgets, shared and per-expression, applying to
+  the team, its sub-teams, and their apps. See
+  [Usage Limits](./usage-limits.mdx).
 - **Members**—who belongs to the team.
 
 ## Adding Team Members

package/docs/ai-gateway/overview.mdx

@@ -30,9 +30,9 @@ Google, Mistral, xAI, and more) dynamically without modifying app code.
 Configure model access through the gateway rather than hard coding it into your
 apps.
 
-**Cost Control**: Set spending limits at gateway, team, and app levels with
-hierarchical budgets that cascade down through your structure. Configure daily
-and monthly thresholds with enforcement or warning notifications.
+**Cost Control**: Set independent spending limits at the gateway, team, and app
+levels. Configure hourly, daily, weekly, or monthly rules that warn or block
+when usage reaches a limit.
 
 **Security & Compliance**: Apply guardrails to detect and block prompt injection
 attempts and prevent PII leakage in both requests and responses through
@@ -99,13 +99,14 @@ a consistent starting pipeline. See [Policy Chains](./policy-chains.mdx) and
 
 ### Team Hierarchy & Budgets
 
-Organize users into teams with hierarchical structures. Set budget limits at
-each level that cascade down:
+Organize users into teams with hierarchical structures. Set a budget at each
+node. Each node totals its own usage and all descendant usage, and any exceeded
+**Block** limit rejects the request:
 
-- **Gateway**: Limits across the Zuplo project (for example, $1,000/day)
-- **Teams**: Team-specific limits that can't exceed parent limits (for example,
-  $500/day for the Credit Team)
-- **Apps**: Per-app limits for granular control
+- **Gateway**: Limits across the Zuplo project (for example, $1,000/day).
+- **Teams**: Limits across the team, its sub-teams, and their apps (for example,
+  $500/day for the Credit Team).
+- **Apps**: Limits for one app's traffic.
 
 See [Usage Limits](./usage-limits.mdx).
 

package/docs/ai-gateway/policy-templates.mdx

@@ -34,11 +34,17 @@ Policies tab.
 
 :::
 
+Everything on the **Policy Template** tab is template content, budgets included:
+a **Budgets and Costs** entry in the template sets the default budget each new
+app starts with in its own chain, and doesn't enforce anything on the team. The
+team's own budgets—shared and per-expression—live on the team's **Usage &
+Limits** tab. See [Usage Limits](./usage-limits.mdx).
+
 ## Editing a template
 
-Open a team and select its **Policies** tab. The template editor works like the
-app chain editor: add policies from the gateway's declared menu, order them, and
-configure their options.
+Open a team and select its **Policy Template** tab. The template editor works
+like the app chain editor: add policies from the gateway's declared menu, order
+them, and configure their options.
 
 Each policy in the template carries two checkboxes that control what an app
 starting from the template may do with that entry. Both start checked—a policy
@@ -55,14 +61,14 @@ by the team policy template".
 ## Inheriting from a parent team
 
 A sub-team can use its parent team's template instead of defining its own,
-controlled by the **Inherit from parent** switch on the sub-team's Policies tab.
-The switch drafts like the page's other edits and applies when you click **Save
-changes**. While inheriting, the sub-team's template is read-only—it shows the
-parent's effective template. Turn the switch off to give the sub-team its own
-template: the editor starts from a copy of the parent's effective template,
-which you then adjust. Turning inheritance back on and saving discards the
-sub-team's own template in favor of the parent's—before you save, flip the
-switch again to restore your draft.
+controlled by the **Inherit from parent** switch on the sub-team's **Policy
+Template** tab. The switch drafts like the page's other edits and applies when
+you click **Save changes**. While inheriting, the sub-team's template is
+read-only—it shows the parent's effective template. Turn the switch off to give
+the sub-team its own template: the editor starts from a copy of the parent's
+effective template, which you then adjust. Turning inheritance back on and
+saving discards the sub-team's own template in favor of the parent's—before you
+save, flip the switch again to restore your draft.
 
 ## Next steps
 

package/docs/ai-gateway/teams.mdx

@@ -18,7 +18,7 @@ on that member's role.
 
 Teams also carry a [policy template](./policy-templates.mdx)—the policy chain
 that apps created in the team start with—and [usage limits](./usage-limits.mdx)
-that apply to all of the team's apps combined.
+that apply to the team's own usage and all descendant sub-teams and apps.
 
 ## Members
 

package/docs/ai-gateway/usage-limits.mdx

@@ -1,9 +1,9 @@
 ---
-title: "Usage Limits & Thresholds"
+title: "Usage Limits & Budget Rules"
 sidebar_label: "Usage Limits"
 description:
-  Set hierarchical spending, token, and request limits at the gateway, team, and
-  app levels, with warning thresholds and quota fallbacks.
+  Set spending, token, and request budgets at the gateway, team, and app levels,
+  and give every metadata value its own separate budget using expression rules.
 ---
 
 The Zuplo AI Gateway provides hierarchical usage limits and budget controls to
@@ -12,40 +12,118 @@ gateway, team, and app levels.
 
 ## Budget Hierarchy
 
-Limits at every level apply together—a request is blocked when _any_ level's
-limit is exceeded, and the error names the level that blocked it:
+Limits at every level apply together. A request is blocked when the gateway, an
+ancestor team, or the app is over a **Block** limit. The error identifies
+whether a shared node budget or an expression-specific budget ran out:
 
 - **Gateway** - Limits across the Zuplo project (for example, $1,000/day),
-  covering all teams and apps combined
-- **Teams** - Team-specific limits covering all of the team's apps combined (for
-  example, $500/day for the Engineering team)
+  covering all teams, sub-teams, and apps combined
+- **Teams** - Limits covering the team's own usage and every descendant sub-team
+  and app (for example, $500/day for the Engineering team)
 - **Apps** - Per-app limits for granular control (for example, $10/day for a
   hackathon app)
 
+Budgets at different levels don't constrain each other's values, and app budgets
+under a team may add up to more than the team's own budget - the team's budget
+is the aggregate cap. For example, take a $100/month team containing a $50/month
+sub-team with two apps capped at $25/month and $40/month. When the apps have
+spent $40 and $10, the sub-team's aggregate reaches $50 and requests through
+**both** apps are blocked - including the app that is still under its own $25
+cap. Apps elsewhere in the $100/month team keep working until that team's own
+aggregate reaches $100.
+
+<Diagram direction="vertical" height="h-96">
+  <DiagramNode id="team" variant="green">
+    Team · spent $50 of $100
+  </DiagramNode>
+  <DiagramNode id="subteam" variant="red">
+    Sub-team · spent $50 of $50
+  </DiagramNode>
+  <DiagramNode id="appa" variant="red">
+    App A · spent $10 of $25
+  </DiagramNode>
+  <DiagramNode id="appb" variant="red">
+    App B · spent $40 of $40
+  </DiagramNode>
+  <DiagramNode id="other" variant="green">
+    Other apps in the team
+  </DiagramNode>
+  <DiagramEdge from="team" to="subteam" label="at its Block limit" />
+  <DiagramEdge from="team" to="other" label="still serving" />
+  <DiagramEdge from="subteam" to="appa" label="blocked — under its own cap" />
+  <DiagramEdge from="subteam" to="appb" label="blocked" />
+</Diagram>
+
 ## Where limits are configured
 
-| Level   | Where                                                                             |
-| ------- | --------------------------------------------------------------------------------- |
-| Gateway | **Settings → Usage Limits**                                                       |
-| Team    | The team's **Usage & Limits** tab                                                 |
-| App     | The **Budgets and Costs** policy in the app's [policy chain](./policy-chains.mdx) |
+| Level   | Shared budget                                                                     | Per-expression budgets                                       |
+| ------- | --------------------------------------------------------------------------------- | ------------------------------------------------------------ |
+| Gateway | **Settings → Usage Limits**                                                       | Supported in configuration, but not authorable in the Portal |
+| Team    | The team's **Usage & Limits** tab                                                 | The team's **Usage & Limits** tab                            |
+| App     | The **Budgets and Costs** policy in the app's [policy chain](./policy-chains.mdx) | The **Budgets and Costs** policy                             |
+
+Gateway and team limits apply independently to every descendant app; they aren't
+copied into the app's configuration. Each node meters its own usage plus all
+descendant usage. A request is blocked if any node in its path is over a
+**Block** limit. An app's own limits live on the Budgets and Costs policy.
+
+:::note
+
+Everything a team enforces lives on its **Usage & Limits** tab. The **Policy
+Template** tab is only the template: a Budgets and Costs entry there is copied
+into each new app as the app's own starting budget and doesn't enforce the
+team's budget.
+
+:::
+
+## How a budget rule works
+
+Every node's budgets are a list of rules. Each rule answers two questions—what
+it budgets, and what the caps are.
+
+**Scope** decides who shares the budget:
+
+| Scope                                      | What it budgets                                                          |
+| ------------------------------------------ | ------------------------------------------------------------------------ |
+| **Shared** (`budgetBy: "app"`)             | One shared budget for the gateway, team, or app and its descendants      |
+| **By metadata** (`budgetBy: "expression"`) | A separate budget at that node for every distinct value of an expression |
+
+A **By metadata** rule gives each distinct expression value its own allowance.
+With the expression `request.headers.get("x-user")` and a $5 daily cap, every
+distinct `x-user` value gets its own $5 per day—one user exhausting their budget
+doesn't affect anyone else. A node can combine a shared rule with several
+expression rules.
+
+Ancestor rules of both kinds apply to every request through the node's subtree.
+The difference is who gets blocked: a team's **Shared** rule blocks all of the
+team's traffic once the team's aggregate is over, while a team's **By metadata**
+rule meters each value across all of the team's apps combined and blocks only
+the exhausted value—the same `x-user` shares one budget whether it calls App A
+or App B.
+
+**Limit rows** set the caps. Each row is a meter, a period, an amount, and an
+action:
 
-Each level supports the same three meters, each with independent daily and
-monthly settings:
+| Field      | Values                                                            |
+| ---------- | ----------------------------------------------------------------- |
+| **Meter**  | Cost (dollars), Tokens (input plus output), Requests              |
+| **Period** | Hourly, Daily, Weekly, Monthly                                    |
+| **Limit**  | An absolute amount in the meter's own unit                        |
+| **Action** | **Block** rejects the request; **Warn** notifies without blocking |
 
-- **Budget** - spend in dollars
-- **Tokens** - input plus output tokens
-- **Requests** - request count
+Add as many rows as you need to cap several meters and periods at once. A Warn
+row and a Block row on the same meter and period give you warn-then-block—warn
+at $80, block at $100. The warn amount has to be the lower of the two.
 
-For each meter and period you can set a **Limit** (usage at or above it gets
-blocked) and a **Warning** threshold (a percentage of the limit that triggers a
-warning notification without blocking). Leave a field empty to not enforce it.
+The **Overview** tab charts daily and monthly usage only. Hourly and weekly rows
+are enforced, but no meter on that tab tracks them.
 
 :::note
 
-Daily and monthly periods are anchored to your gateway, not the calendar: a
-daily period rolls over at the time of day (UTC) the gateway was created, and a
-monthly period runs anchor-day to anchor-day. Changing a limit mid-period
+Periods are anchored to your gateway, not the calendar. Every period rolls over
+relative to the time (UTC) the gateway was created, so a daily period resets at
+that hour rather than at midnight, and a monthly one on that day of the month.
+Teams and apps created later use the same anchor. Changing a limit mid-period
 doesn't reset the period's usage.
 
 :::
@@ -60,43 +138,114 @@ doesn't reset the period's usage.
 1. On the **Policies** tab, configure the **Budgets and Costs** policy (add it
    from **Add Policy** if the chain doesn't have it).
 
-1. Set daily or monthly limits for budget, tokens, or requests, and optional
-   warning thresholds.
+1. Select **Add rule**, choose the scope, and use **Add limit** to add rows for
+   the meters and periods you want to cap. For a **By metadata** rule, enter the
+   expression that identifies each caller.
 
-1. Save. The change applies within about a minute.
+1. Select **Apply**, then **Save changes** on the policy chain. The change
+   applies within about a minute.
 
 </Stepper>
 
-:::note
+The app editor groups gateway and ancestor team rules under **Inherited**. Those
+rules remain stored and enforced at the gateway or team; edit them where they
+were created.
 
-Each period in the Budgets and Costs policy's options carries an `enabled` flag
-next to its number, and so does each warning threshold. A period enforces
-nothing until `enabled` is `true` _and_ `limit` is set—options that set only
-`limit` are silently inert. Watch for this when editing the policy's options
-directly, such as in `config/policies.json` or a
-[policy template](./policy-templates.mdx).
+### Budget expressions
 
-:::
+A **By metadata** rule identifies each caller with an expression evaluated per
+request. The editor validates it as you type. Available values include:
 
-If the app has a **quota fallback** model configured, an exceeded limit routes
-requests to that model instead of blocking with a `429`—see
-[Fallback Models](./fallback.mdx). The fallback's usage still counts toward the
-limits.
+- `request.headers.get("x-user")` and other request headers
+- `request.user.sub` and `request.user.data.<key>` from the authenticated API
+  key
+- `request.url`, `request.method`, `request.query`, `request.searchParams`, and
+  `request.params`
+- `context.contextId`, `context.requestId`, `context.route`, and
+  `context.custom`
+
+The editor labels each expression by where its value comes from, because that
+decides how much the budget can be trusted. A **client-supplied** value—a header
+or query parameter—is attribution, not enforcement: a caller who changes it gets
+a fresh budget. Budget on `request.user.*`, labeled **verified**, when the
+segment itself has to hold, and keep a shared-budget rule alongside it as the
+hard cap.
 
-:::note{title="App, team, and gateway limits are configured separately"}
+:::caution
 
-The Budgets and Costs policy configures and enforces an app's own limits. Team
-and gateway limits apply to every app automatically, whether or not the app's
-policy chain includes Budgets and Costs.
+Changing an expression starts a new budget. The old rule's usage stays with the
+old expression, so every value's accounting restarts from zero. Expressions are
+also case-sensitive: `get("X-User")` and `get("x-user")` read the same header
+but budget separately.
 
 :::
 
+App rules are stored in `options.budgetRules` on the app's own Budgets and Costs
+policy entry. For the app rule schema, see the
+[Budgets and Costs policy reference](../policies/ai-gateway-metering-v2-inbound.mdx).
+
+## Setting team and gateway limits
+
+Team and gateway limits cover the node's own usage and all descendant usage.
+They apply to every descendant app whether or not its chain includes Budgets and
+Costs.
+
+Team rules—shared and per-expression—are added on the team's **Usage & Limits**
+tab, using the same meter, period, amount, and action rows as the app editor.
+
+To add a shared gateway rule, open **Settings → Usage Limits**. The gateway root
+supports per-expression rules in `metadata.budgetRules`, but the Portal doesn't
+author them. It displays a stored expression rule as read-only and lets you
+delete it.
+
+Each `budgetBy: "app"` rule is a shared budget for the node where the rule is
+stored. At the gateway or team level, `app` means that gateway or team node, not
+an app policy configuration. A team's usage includes its sub-teams and apps, and
+the gateway's usage includes the whole project.
+
+Gateway and team rules are stored in `metadata.budgetRules` on that node. The
+editor groups ancestor rules under **Inherited**, but each rule remains enforced
+at the node where it was created.
+
+## When a limit is exceeded
+
+If the app has a **quota fallback** model configured, an exceeded limit routes
+requests to that model instead of blocking—see
+[Fallback Models](./fallback.mdx), where the fallback model is selected. This
+applies to gateway and team limits as well as the app's own. The fallback's
+usage still counts toward the limits.
+
+Without a fallback, the request is rejected with `429 Too Many Requests` and a
+`budget` object naming what ran out:
+
+```json
+{
+  "type": "https://httpproblems.com/http-status/429",
+  "title": "Too Many Requests",
+  "detail": "Your daily cost budget has been exhausted (limit: 5).",
+  "budget": {
+    "scope": "dimension",
+    "dimensionedBy": "request.headers.get(\"x-user\")",
+    "ruleId": "3f2a9c1b",
+    "meter": "cost",
+    "window": "daily",
+    "limit": 5
+  }
+}
+```
+
+The `scope` tells the caller which budget they hit. It is `application` when the
+gateway, a team, or the app exhausts a shared node budget. It is `dimension`
+when a value exhausts an expression budget. Quote the `ruleId` when raising a
+support request.
+
 :::caution{title="Budgets fail open by default"}
 
-The Budgets and Costs policy's `throwOnFailure` option controls how an error
-while checking the app's own limits is handled. It defaults to `false`, so the
-request continues through the gateway. Set it to `true` to reject the request
-instead. Team and gateway limit checks run independently of this policy.
+The Budgets and Costs policy's `throwOnFailure` option—**Fail closed when
+metering is unavailable** in the editor—controls how an error while checking the
+app's own limits is handled. It defaults to `false`, so the request continues
+through the gateway. Set it to `true` to reject the request instead. Team and
+gateway limit checks run independently of this policy.
 
 :::
 

package/docs/articles/api-key-administration.mdx

@@ -13,8 +13,8 @@ environments.
 ![The API Keys → Consumers page in the Services section, with the sidebar showing API Keys, Monetization, and Audit Logs, and the environment switcher set to Dev](../../public/media/api-key-administration/services-page.png)
 
 To view the bucket for a different environment, use the **Dev / Preview / Prod**
-switcher at the top of the sidebar. Click **Bucket Details** under the **API Key
-Service** heading to copy the active bucket's name or ID.
+switcher at the top of the sidebar. Copy the active bucket's ID from the
+**Bucket ID** pill under the **API Key Service** heading.
 
 To add a new API Key Consumer, click **Create Consumer** and complete the form.
 

package/docs/articles/api-key-api.mdx

@@ -84,12 +84,33 @@ inside Zuplo)
 ```bash
 # Your Zuplo Account Name
 export ACCOUNT_NAME=my-account
-# Your bucket name (Found in Services > API Key Service)
-export BUCKET_NAME=my-bucket
+# Your bucket ID (Found in Services > API Keys > Consumers)
+export BUCKET_ID=bckt_2HaK3odRyJle6NJSu8mzNKBC30BYxllxL
 # Your Zuplo API Key (Found in Account Settings > Zuplo API Keys)
 export API_KEY=zpka_YOUR_API_KEY
 ```
 
+For more information about finding the bucket ID, see
+[Bucket identifiers](./api-key-buckets.mdx#bucket-identifiers).
+
+<details>
+<summary>Legacy: identifying a bucket by name (deprecated)</summary>
+
+The consumer, key, and manager endpoints also accept a bucket name in place of
+the bucket ID, so existing scripts keep working:
+
+```bash
+export BUCKET_NAME=my-bucket
+curl \
+  https://dev.zuplo.com/v1/accounts/$ACCOUNT_NAME/key-buckets/$BUCKET_NAME/consumers \
+  --header "Authorization: Bearer $API_KEY"
+```
+
+The Zuplo Portal doesn't display bucket names, so use the bucket ID in new code.
+When a value matches both a bucket name and a bucket ID, the name wins.
+
+</details>
+
 ### Creating a Consumer with a Key
 
 When creating a new Consumer, it's a good idea to include some useful metadata
@@ -101,7 +122,7 @@ external identifier that links this consumer to your internal data as a tag.
 
 ```shell
 curl \
-  https://dev.zuplo.com/v1/accounts/$ACCOUNT_NAME/key-buckets/$BUCKET_NAME/consumers?with-api-key=true \
+  https://dev.zuplo.com/v1/accounts/$ACCOUNT_NAME/key-buckets/$BUCKET_ID/consumers?with-api-key=true \
   --request POST \
   --header "Content-type: application/json" \
   --header "Authorization: Bearer $API_KEY" \
@@ -156,7 +177,7 @@ You can use this API Key to call your Zuplo Gateway that's protected by the
 ```shell
 export ORG_ID=1234
 curl \
-  https://dev.zuplo.com/v1/accounts/$ACCOUNT_NAME/key-buckets/$BUCKET_NAME/consumers/?include-api-keys=true&key-format=visible&tag.orgId=$ORG_ID \
+  https://dev.zuplo.com/v1/accounts/$ACCOUNT_NAME/key-buckets/$BUCKET_ID/consumers/?include-api-keys=true&key-format=visible&tag.orgId=$ORG_ID \
   --header "Authorization: Bearer $API_KEY"
 ```
 
@@ -248,7 +269,7 @@ creates a new key without an expiration.
 export ORG_ID=1234
 export CONSUMER_NAME=my-consumer
 curl \
-  https://dev.zuplo.com/v1/accounts/$ACCOUNT_NAME/key-buckets/$BUCKET_NAME/consumers/$CONSUMER_NAME/roll-key?tag.orgId=$ORG_ID \
+  https://dev.zuplo.com/v1/accounts/$ACCOUNT_NAME/key-buckets/$BUCKET_ID/consumers/$CONSUMER_NAME/roll-key?tag.orgId=$ORG_ID \
   --request POST \
   --header "Authorization: Bearer $API_KEY" \
   --header "Content-Type: application/json" \

package/docs/articles/api-key-authentication.mdx

@@ -144,7 +144,7 @@ development.
 Either locally or in CI/CD you can specify any API Key bucket on the
 [API Key Authentication](../policies/api-key-inbound.mdx) policy by setting the
 `bucketId` property. Every environment can then share a single bucket that holds
-the consumers your tests need. Find a bucket's ID under **Bucket Details** on
+the consumers your tests need. Find a bucket's ID on the **Bucket ID** pill on
 the
 [**Services → API Keys → Consumers**](https://portal.zuplo.com/+/account/project/services)
 page in the Zuplo Portal. You can use the

package/docs/articles/api-key-buckets.mdx

@@ -21,6 +21,31 @@ Zuplo automatically creates three buckets for each project:
 For more information on how environments relate to Git branches, see
 [Branch-Based Deployments](./branch-based-deployments.mdx).
 
+## Bucket identifiers
+
+Every bucket has an ID that starts with `bckt_`, and a name. Use the bucket ID
+whenever you identify a bucket, both in the
+[Zuplo Developer API](./api-key-api.mdx) and in policy configuration. To copy
+it, open
+[**Services → API Keys → Consumers**](https://portal.zuplo.com/+/account/project/services)
+in the Zuplo Portal and select the environment with the **Dev / Preview / Prod**
+switcher. The **Bucket ID** pill sits beside the environment badge under the
+**API Key Service** heading, with a copy button.
+
+:::caution{title="Deprecated"}
+
+The bucket name is a legacy identifier. The Zuplo Portal doesn't display it, and
+the Developer API accepts it only for backward compatibility on the consumer,
+key, and manager endpoints. Pass the bucket ID instead.
+
+Three endpoints are the exception and still require the bucket name:
+
+- `GET /v1/accounts/{accountName}/key-buckets/{bucketName}`
+- `PATCH /v1/accounts/{accountName}/key-buckets/{bucketName}`
+- `DELETE /v1/accounts/{accountName}/key-buckets/{bucketName}`
+
+:::
+
 ## Custom bucket configuration
 
 To use a custom bucket, specify its `bucketId` in your API Key policy options:
@@ -36,10 +61,8 @@ To use a custom bucket, specify its `bucketId` in your API Key policy options:
 }
 ```
 
-Bucket IDs start with `bckt_`. To find one, open
-[**Services → API Keys → Consumers**](https://portal.zuplo.com/+/account/project/services)
-in the Zuplo Portal, select the environment with the **Dev / Preview / Prod**
-switcher, then click **Bucket Details**.
+For more information about finding a bucket ID, see
+[Bucket identifiers](#bucket-identifiers).
 
 When the configuration sets no bucket, the policy uses the default bucket for
 the current environment.

package/docs/articles/api-key-consumer-bucket-portal-ui.mdx

@@ -65,20 +65,20 @@ For deeper detail, see [Buckets and Environments](./api-key-buckets.mdx).
 1. Use the **Dev / Preview / Prod** switcher at the top of the sidebar to select
    the environment whose bucket you want.
 
-1. Click **Bucket Details** under the **API Key Service** heading to see the
-   active bucket's name and ID, each with a copy button.
+1. Copy the active bucket's ID from the **Bucket ID** pill beside the
+   environment badge under the **API Key Service** heading.
 
 </Stepper>
 
 <ModalScreenshot size="md">
 
-![The API Keys → Consumers page with the environment switcher set to Dev and the Bucket Details button under the API Key Service heading](../../public/media/api-key-consumer-bucket-portal-ui/services-page-dropdown.png)
+![The API Keys → Consumers page with the environment switcher set to Dev and the Bucket ID pill under the API Key Service heading](../../public/media/api-key-consumer-bucket-portal-ui/services-page-dropdown.png)
 
 </ModalScreenshot>
 
-**Bucket Details** shows the name and ID of the bucket that's currently active
-for the selected environment. Bucket IDs start with `bckt_` — this is the value
-the API Key Authentication policy's `bucketId` option takes.
+The **Bucket ID** pill shows the ID of the bucket that's currently active for
+the selected environment. Bucket IDs start with `bckt_` — this is the value the
+API Key Authentication policy's `bucketId` option takes.
 
 ## Create a consumer in a specific bucket
 
@@ -157,7 +157,7 @@ the [Zuplo Developer API](./api-key-api.mdx):
 
 ```bash
 curl \
-  https://dev.zuplo.com/v1/accounts/$ACCOUNT_NAME/key-buckets/$BUCKET_NAME/consumers?with-api-key=true \
+  https://dev.zuplo.com/v1/accounts/$ACCOUNT_NAME/key-buckets/$BUCKET_ID/consumers?with-api-key=true \
   --request POST \
   --header "Content-type: application/json" \
   --header "Authorization: Bearer $ZAPI_KEY" \
@@ -168,10 +168,12 @@ curl \
   }'
 ```
 
-Replace `$ACCOUNT_NAME` with your Zuplo account name, `$BUCKET_NAME` with the
-target bucket name, and `$ZAPI_KEY` with your
-[Zuplo API key](./accounts/zuplo-api-keys.mdx). Full reference at the
-[Developer API documentation](https://dev.zuplo.com/docs).
+Replace `$ACCOUNT_NAME` with your Zuplo account name, `$BUCKET_ID` with the
+target bucket's ID, and `$ZAPI_KEY` with your
+[Zuplo API key](./accounts/zuplo-api-keys.mdx). The bucket name also works here,
+but it's deprecated. For more information, see
+[Bucket identifiers](./api-key-buckets.mdx#bucket-identifiers). Full reference
+at the [Developer API documentation](https://dev.zuplo.com/docs).
 
 ## Troubleshooting
 

package/docs/articles/api-key-leak-detection.mdx

@@ -64,12 +64,12 @@ their integration, or omit it to revoke the old key immediately.
 
 ```bash
 export ACCOUNT_NAME="your-account-name"
-export BUCKET_NAME="your-bucket-name"
+export BUCKET_ID="your-bucket-id"
 export CONSUMER_NAME="your-consumer-name"
 export ZUPLO_API_KEY="your-zuplo-api-key"
 
 curl --request POST \
-  --url https://dev.zuplo.com/v1/accounts/$ACCOUNT_NAME/key-buckets/$BUCKET_NAME/consumers/$CONSUMER_NAME/roll-key \
+  --url https://dev.zuplo.com/v1/accounts/$ACCOUNT_NAME/key-buckets/$BUCKET_ID/consumers/$CONSUMER_NAME/roll-key \
   --header 'Authorization: Bearer $ZUPLO_API_KEY' \
   --header 'Content-Type: application/json' \
   --data '

package/docs/articles/api-key-self-serve-integration.mdx

@@ -51,12 +51,12 @@ Before you start, you need:
   under
   [**Account Settings → Zuplo API Keys**](https://portal.zuplo.com/+/account/settings/api-keys).
   [More information](./accounts/zuplo-api-keys).
-- Your **account name** and **bucket name**. A bucket groups consumers for an
+- Your **account name** and **bucket ID**. A bucket groups consumers for an
   environment - each project has buckets for production, preview, and
-  development. Find the bucket name on your project's
+  development. Copy the bucket ID from the **Bucket ID** pill next to the **API
+  Key Service** heading on your project's
   [**Services → API Keys → Consumers**](https://portal.zuplo.com/+/account/project/services)
-  page (under **Bucket Details**, next to the **API Key Service** heading), and
-  the account name in
+  page, and the account name from
   [**Project Settings → General**](https://portal.zuplo.com/+/account/project/settings/general).
 - An application with server-side code and existing user authentication.
 
@@ -65,8 +65,8 @@ All examples in this guide use these environment variables:
 ```bash
 # Your Zuplo Account Name
 export ZUPLO_ACCOUNT=my-account
-# Your bucket name (found on the Services → API Keys → Consumers page)
-export ZUPLO_BUCKET=my-bucket
+# Your bucket ID (found on the Services → API Keys → Consumers page)
+export ZUPLO_BUCKET_ID=bckt_2HaK3odRyJle6NJSu8mzNKBC30BYxllxL
 # Your Zuplo API Key (found in Account Settings > Zuplo API Keys)
 export ZUPLO_API_KEY=zpka_YOUR_API_KEY
 ```
@@ -128,7 +128,7 @@ initial API key in a single call by passing `?with-api-key=true`:
 
 ```shell
 curl \
-  https://dev.zuplo.com/v1/accounts/$ZUPLO_ACCOUNT/key-buckets/$ZUPLO_BUCKET/consumers?with-api-key=true \
+  https://dev.zuplo.com/v1/accounts/$ZUPLO_ACCOUNT/key-buckets/$ZUPLO_BUCKET_ID/consumers?with-api-key=true \
   --request POST \
   --header "Content-Type: application/json" \
   --header "Authorization: Bearer $ZUPLO_API_KEY" \
@@ -189,7 +189,7 @@ To render an "API Keys" page in your settings, fetch the consumer's keys:
 
 ```shell
 curl \
-  https://dev.zuplo.com/v1/accounts/$ZUPLO_ACCOUNT/key-buckets/$ZUPLO_BUCKET/consumers/org_123/keys?key-format=masked \
+  https://dev.zuplo.com/v1/accounts/$ZUPLO_ACCOUNT/key-buckets/$ZUPLO_BUCKET_ID/consumers/org_123/keys?key-format=masked \
   --header "Authorization: Bearer $ZUPLO_API_KEY"
 ```
 
@@ -224,7 +224,7 @@ staging and production), create a key directly:
 
 ```shell
 curl \
-  https://dev.zuplo.com/v1/accounts/$ZUPLO_ACCOUNT/key-buckets/$ZUPLO_BUCKET/consumers/org_123/keys \
+  https://dev.zuplo.com/v1/accounts/$ZUPLO_ACCOUNT/key-buckets/$ZUPLO_BUCKET_ID/consumers/org_123/keys \
   --request POST \
   --header "Content-Type: application/json" \
   --header "Authorization: Bearer $ZUPLO_API_KEY" \
@@ -238,7 +238,7 @@ the user a transition period to switch over. Use the roll-key endpoint:
 
 ```shell
 curl \
-  https://dev.zuplo.com/v1/accounts/$ZUPLO_ACCOUNT/key-buckets/$ZUPLO_BUCKET/consumers/org_123/roll-key \
+  https://dev.zuplo.com/v1/accounts/$ZUPLO_ACCOUNT/key-buckets/$ZUPLO_BUCKET_ID/consumers/org_123/roll-key \
   --request POST \
   --header "Content-Type: application/json" \
   --header "Authorization: Bearer $ZUPLO_API_KEY" \
@@ -261,7 +261,7 @@ To let users revoke a specific key immediately:
 
 ```shell
 curl \
-  https://dev.zuplo.com/v1/accounts/$ZUPLO_ACCOUNT/key-buckets/$ZUPLO_BUCKET/consumers/org_123/keys/key_AM7eAiR0BiaXTam951XmC9kK \
+  https://dev.zuplo.com/v1/accounts/$ZUPLO_ACCOUNT/key-buckets/$ZUPLO_BUCKET_ID/consumers/org_123/keys/key_AM7eAiR0BiaXTam951XmC9kK \
   --request DELETE \
   --header "Authorization: Bearer $ZUPLO_API_KEY"
 ```
@@ -282,7 +282,7 @@ runtime, patch the consumer:
 
 ```shell
 curl \
-  https://dev.zuplo.com/v1/accounts/$ZUPLO_ACCOUNT/key-buckets/$ZUPLO_BUCKET/consumers/org_123 \
+  https://dev.zuplo.com/v1/accounts/$ZUPLO_ACCOUNT/key-buckets/$ZUPLO_BUCKET_ID/consumers/org_123 \
   --request PATCH \
   --header "Content-Type: application/json" \
   --header "Authorization: Bearer $ZUPLO_API_KEY" \
@@ -305,12 +305,12 @@ append `?tag.orgId=org_123` to every call:
 ```shell
 # List only consumers belonging to org_123
 curl \
-  "https://dev.zuplo.com/v1/accounts/$ZUPLO_ACCOUNT/key-buckets/$ZUPLO_BUCKET/consumers?tag.orgId=org_123&include-api-keys=true&key-format=masked" \
+  "https://dev.zuplo.com/v1/accounts/$ZUPLO_ACCOUNT/key-buckets/$ZUPLO_BUCKET_ID/consumers?tag.orgId=org_123&include-api-keys=true&key-format=masked" \
   --header "Authorization: Bearer $ZUPLO_API_KEY"
 
 # Delete a consumer - fails if the consumer doesn't have tag orgId=org_123
 curl \
-  "https://dev.zuplo.com/v1/accounts/$ZUPLO_ACCOUNT/key-buckets/$ZUPLO_BUCKET/consumers/org_123?tag.orgId=org_123" \
+  "https://dev.zuplo.com/v1/accounts/$ZUPLO_ACCOUNT/key-buckets/$ZUPLO_BUCKET_ID/consumers/org_123?tag.orgId=org_123" \
   --request DELETE \
   --header "Authorization: Bearer $ZUPLO_API_KEY"
 ```
@@ -333,7 +333,7 @@ app.use(express.json());
 
 const ZUPLO_BASE = "https://dev.zuplo.com/v1/accounts";
 const ZUPLO_ACCOUNT = process.env.ZUPLO_ACCOUNT;
-const ZUPLO_BUCKET = process.env.ZUPLO_BUCKET;
+const ZUPLO_BUCKET_ID = process.env.ZUPLO_BUCKET_ID;
 const ZUPLO_API_KEY = process.env.ZUPLO_API_KEY;
 
 // TODO: Replace with your real auth middleware
@@ -351,7 +351,7 @@ app.get("/api/keys", async (req, res) => {
   if (!orgId) return res.status(401).json({ error: "Unauthorized" });
 
   const response = await fetch(
-    `${ZUPLO_BASE}/${ZUPLO_ACCOUNT}/key-buckets/${ZUPLO_BUCKET}/consumers/${orgId}/keys?key-format=masked`,
+    `${ZUPLO_BASE}/${ZUPLO_ACCOUNT}/key-buckets/${ZUPLO_BUCKET_ID}/consumers/${orgId}/keys?key-format=masked`,
     {
       headers: { Authorization: `Bearer ${ZUPLO_API_KEY}` },
     },
@@ -366,7 +366,7 @@ app.post("/api/keys", async (req, res) => {
   if (!orgId) return res.status(401).json({ error: "Unauthorized" });
 
   const response = await fetch(
-    `${ZUPLO_BASE}/${ZUPLO_ACCOUNT}/key-buckets/${ZUPLO_BUCKET}/consumers/${orgId}/keys`,
+    `${ZUPLO_BASE}/${ZUPLO_ACCOUNT}/key-buckets/${ZUPLO_BUCKET_ID}/consumers/${orgId}/keys`,
     {
       method: "POST",
       headers: {
@@ -386,7 +386,7 @@ app.post("/api/keys/rotate", async (req, res) => {
   if (!orgId) return res.status(401).json({ error: "Unauthorized" });
 
   const response = await fetch(
-    `${ZUPLO_BASE}/${ZUPLO_ACCOUNT}/key-buckets/${ZUPLO_BUCKET}/consumers/${orgId}/roll-key?tag.orgId=${orgId}`,
+    `${ZUPLO_BASE}/${ZUPLO_ACCOUNT}/key-buckets/${ZUPLO_BUCKET_ID}/consumers/${orgId}/roll-key?tag.orgId=${orgId}`,
     {
       method: "POST",
       headers: {
@@ -406,7 +406,7 @@ app.delete("/api/keys/:keyId", async (req, res) => {
   if (!orgId) return res.status(401).json({ error: "Unauthorized" });
 
   const response = await fetch(
-    `${ZUPLO_BASE}/${ZUPLO_ACCOUNT}/key-buckets/${ZUPLO_BUCKET}/consumers/${orgId}/keys/${req.params.keyId}?tag.orgId=${orgId}`,
+    `${ZUPLO_BASE}/${ZUPLO_ACCOUNT}/key-buckets/${ZUPLO_BUCKET_ID}/consumers/${orgId}/keys/${req.params.keyId}?tag.orgId=${orgId}`,
     {
       method: "DELETE",
       headers: { Authorization: `Bearer ${ZUPLO_API_KEY}` },

package/docs/articles/audit-logs.mdx

@@ -121,12 +121,13 @@ The events view lets you:
 Everything in the portal is backed by the Zuplo API, so you can query audit logs
 programmatically — for scripting, custom dashboards, or exporting to other
 systems. Authenticate with a [Zuplo API key](./accounts/zuplo-api-keys.mdx) and
-query events by bucket name. Your bucket name is shown on the **API Keys →
-Consumers** page in the portal, as the copyable pill under the **API Key
-Service** heading (it's the same bucket used by the API Key Service).
+query events by bucket ID. Copy the bucket ID from the copyable **Bucket ID**
+pill under the **API Key Service** heading on the
+[**Services → API Keys → Consumers**](https://portal.zuplo.com/+/account/project/services)
+page in the portal (it's the same bucket used by the API Key Service).
 
 ```bash
-curl "https://dev.zuplo.com/v1/audit-logs/$BUCKET_NAME/events?type=com.zuplo.api.request&startDate=2026-07-01T00:00:00Z&endDate=2026-07-07T00:00:00Z" \
+curl "https://dev.zuplo.com/v1/audit-logs/$BUCKET_ID/events?type=com.zuplo.api.request&startDate=2026-07-01T00:00:00Z&endDate=2026-07-07T00:00:00Z" \
   -H "Authorization: Bearer $ZUPLO_API_KEY"
 ```
 
@@ -163,10 +164,10 @@ Two endpoints are available:
 - **Aggregated stats** — `GET /v1/audit-logs/{bucketId}/stats` returns top-N
   event counts grouped by event type or actor.
 
-The `bucketId` path parameter accepts either the bucket ID or the bucket name.
-Each query is limited to a 30-day window between `startDate` and `endDate`. See
-the [Audit Logs API reference](../api/audit-logs) for all parameters and
-response schemas.
+The `bucketId` path parameter takes the bucket ID; these endpoints don't accept
+a bucket name. Each query is limited to a 30-day window between `startDate` and
+`endDate`. See the [Audit Logs API reference](../api/audit-logs) for all
+parameters and response schemas.
 
 ## Exporting audit logs to a SIEM
 
@@ -182,14 +183,14 @@ const BASE_URL = "https://dev.zuplo.com/v1/audit-logs";
 // Run on a schedule (e.g. every 5 minutes). `startDate` is the checkpoint
 // saved by the previous run; `endDate` is the current time.
 async function exportAuditLogs(
-  bucketName: string,
+  bucketId: string,
   startDate: string,
   endDate: string,
 ) {
   let offset = 0;
   let hasMore = true;
   while (hasMore) {
-    const url = new URL(`${BASE_URL}/${bucketName}/events`);
+    const url = new URL(`${BASE_URL}/${bucketId}/events`);
     url.searchParams.set("startDate", startDate);
     url.searchParams.set("endDate", endDate);
     url.searchParams.set("limit", "100");

package/docs/articles/monetization/api-access.mdx

@@ -37,7 +37,7 @@ are set in your terminal:
 
 ```bash
 # Your Bucket ID (could be working-copy, preview, or production)
-# (Copy it from Bucket Details on Services > API Keys > Consumers — https://portal.zuplo.com/+/account/project/services)
+# (Copy it from the Bucket ID pill on Services > API Keys > Consumers — https://portal.zuplo.com/+/account/project/services)
 export BUCKET_ID=your-bucket-id
 # Your Zuplo API Key (Found in Account Settings > Zuplo API Keys —
 # https://portal.zuplo.com/+/account/settings/api-keys)

package/docs/articles/monetization/going-to-production.mdx

@@ -459,7 +459,7 @@ To help the team resolve your issue quickly, include:
 | ------------------ | ------------------------------------------------------ |
 | Account slug       | Your Zuplo account identifier                          |
 | Project slug       | The project with monetization enabled                  |
-| Bucket ID          | Bucket Details on Services → API Keys → Consumers      |
+| Bucket ID          | The Bucket ID pill on Services → API Keys → Consumers  |
 | Stripe account ID  | Stripe Dashboard → Settings, starts with `acct_`       |
 | Plan keys          | The plan keys involved in the issue                    |
 | Subscription ID    | If the issue is subscription-specific                  |

package/docs/concepts/ai-gateway.mdx

@@ -21,9 +21,10 @@ Three building blocks organize an AI Gateway:
   can route to. Administrators configure providers once, including any
   [custom OpenAI-compatible providers](../ai-gateway/custom-providers.mdx), and
   consumers never see the underlying credentials.
-- **[Teams](../ai-gateway/teams.mdx)** group users and carry budget limits that
-  cascade down the hierarchy: gateway-wide limits, then team limits, then
-  per-app limits. See [Usage Limits](../ai-gateway/usage-limits.mdx).
+- **[Teams](../ai-gateway/teams.mdx)** group users and carry budget limits. Each
+  team totals usage across its sub-teams and apps. A request must remain within
+  the gateway, ancestor team, and app limits. See
+  [Usage Limits](../ai-gateway/usage-limits.mdx).
 - **[Apps](../ai-gateway/apps.mdx)** are the pieces of software that call the
   gateway — a support chatbot is one app, an internal coding agent is another.
   Each app gets its own gateway URL, its own Zuplo-managed API key, and its own

package/docs/concepts/api-keys.md

@@ -187,7 +187,7 @@ Each project has separate buckets for production, preview, and working copy
 environments. This means API keys created in production don't work in preview,
 and vice versa.
 
-For testing, you can specify a custom bucket name on the
+For testing, you can specify a custom bucket ID on the
 [API Key Authentication](../policies/api-key-inbound.mdx) policy to share keys
 across environments. Enterprise customers can share buckets across projects or
 accounts.

package/docs/dedicated/akamai/ai-powered-applications.mdx

@@ -165,14 +165,17 @@ When the firewall detects a threat, it can take one of three actions:
 
 ## Cost and Usage Controls
 
-The Zuplo AI Gateway provides hierarchical budget controls to manage AI
-spending:
-
-- **Organization limits** - Maximum daily and monthly spending across all AI
-  usage
-- **Team budgets** - Allocated budgets for departments or customer segments
-- **Application limits** - Per-application or per-use-case cost controls
-- **Rate limiting** - Request throttling to prevent abuse
+The Zuplo AI Gateway provides budget controls at every level of the hierarchy to
+manage AI spending:
+
+- **Gateway budgets** - Hourly, daily, weekly, or monthly limits across all AI
+  Gateway usage.
+- **Team budgets** - Shared or per-expression limits across a team, its
+  sub-teams, and their apps.
+- **App budgets** - Shared or per-expression limits for one app.
+- **Rate limiting** - Request throttling to prevent abuse.
+
+For more information, see [Usage Limits](../../ai-gateway/usage-limits.mdx).
 
 ## Security Model
 

package/docs/dev-portal/dev-portal-create-consumer-on-auth.mdx

@@ -56,14 +56,19 @@ secret `API_KEY` and set the value.
 
 :::info
 
-In the code below set the variable `BUCKET_NAME` to the bucket being used by
-your Zuplo Gateway. If you don't know the name of your bucket, you can
+In the code below set the variable `API_KEY_BUCKET_ID` to the ID of the bucket
+being used by your Zuplo Gateway. Copy it from the **Bucket ID** pill on your
+project's
+[**Services → API Keys → Consumers**](https://portal.zuplo.com/+/account/project/services)
+page, or
 [list your buckets using the Developer API](https://dev.zuplo.com/docs/routes#apikeybucketsservice_list).
+For more information, see
+[Bucket identifiers](../articles/api-key-buckets.mdx#bucket-identifiers).
 
 :::
 
 Next, add the following code to your custom action. Be sure to replace the
-placeholder values with your actual account and bucket names. Click the
+placeholder values with your actual account name and bucket ID. Click the
 **Deploy** button when you are finished.
 
 ```ts
@@ -71,7 +76,7 @@ const { fetch } = require("undici");
 const { randomUUID } = require("crypto");
 
 const ZUPLO_ACCOUNT = "my-zuplo-account";
-const API_KEY_BUCKET = "my-bucket";
+const API_KEY_BUCKET_ID = "bckt_2HaK3odRyJle6NJSu8mzNKBC30BYxllxL";
 
 /**
  * Handler that will be called during the execution of a PostLogin flow.
@@ -100,7 +105,7 @@ exports.onExecutePostLogin = async (event, api) => {
   try {
     // Create the consumer
     const response = await fetch(
-      `https://dev.zuplo.com/v1/accounts/${ZUPLO_ACCOUNT}/key-buckets/${API_KEY_BUCKET}/consumers?with-api-key=true`,
+      `https://dev.zuplo.com/v1/accounts/${ZUPLO_ACCOUNT}/key-buckets/${API_KEY_BUCKET_ID}/consumers?with-api-key=true`,
       {
         method: "POST",
         body: JSON.stringify(body),

package/docs/policies/ai-gateway-configuration-executor-v2-inbound/doc.md

@@ -319,7 +319,7 @@ selected from the request. Each expression rule requires one or more meter rows:
 | `meter`    | `cost`, `requests`, `tokens`                         |
 | `period`   | `hourly`, `daily`, `weekly`, `monthly`               |
 | `action`   | `warn` records a warning; `block` returns HTTP `429` |
-| `value`    | A finite number greater than or equal to zero        |
+| `value`    | A finite number greater than zero                    |
 
 A rule cannot repeat the same meter, period, and action. When a meter and period
 have both actions, the `warn` value must be less than the `block` value. The

package/docs/policies/ai-gateway-metering-v2-inbound/schema.json

@@ -103,7 +103,7 @@
                         },
                         "value": {
                           "type": "number",
-                          "minimum": 0
+                          "exclusiveMinimum": 0
                         },
                         "action": {
                           "type": "string",

package/docs/policies/semantic-cache-inbound/schema.json

@@ -61,8 +61,12 @@
             },
             "cacheByPropertyPath": {
               "type": "string",
-              "description": "The path to the property in the request body (JSON) to use as cache key. For example '.userId' would read the 'userId' property from the request body. Only works with cacheBy=propertyPath.",
-              "examples": [".userId", ".data.customerId"]
+              "description": "A light path selector into the JSON request body to use as the cache key. Start with `.` for dot notation or `[` for a quoted key containing dots or slashes, for example `.userId`, `.data.customerId`, or `[\"https://example.com/cache-key\"]`. Only works with cacheBy=propertyPath.",
+              "examples": [
+                ".userId",
+                ".data.customerId",
+                "[\"https://example.com/cache-key\"]"
+              ]
             },
             "cacheByFunction": {
               "type": "object",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zuplo",
-  "version": "7.6.3",
+  "version": "7.6.5",
   "type": "module",
   "description": "The official Zuplo CLI for local development and platform management",
   "homepage": "https://zuplo.com/docs/cli/overview",
@@ -32,9 +32,9 @@
     "zuplo": "zuplo.js"
   },
   "dependencies": {
-    "@zuplo/cli": "7.6.3",
-    "@zuplo/core": "7.6.3",
-    "@zuplo/runtime": "7.6.3",
-    "@zuplo/test": "7.6.3"
+    "@zuplo/cli": "7.6.5",
+    "@zuplo/core": "7.6.5",
+    "@zuplo/runtime": "7.6.5",
+    "@zuplo/test": "7.6.5"
   }
 }