---
title: "Update shadow box settings"
method: PATCH
path: "/v1/shadow-box/settings"
tags: ["Shadow Box"]
---

# Update shadow box settings

`PATCH /v1/shadow-box/settings`

## Request

- Base URL: `https://{dataplane_api_url}`
- URL: `https://{dataplane_api_url}/v1/shadow-box/settings`
- Auth: OAuth 2
  - Implicit: `https://auth.prd.cloud.redpanda.com/oauth/authorize`

Update the settings that the next box uses. A change also applies to a box that is in place.

## Request body

- UpdateShadowBoxSettingsRequest: `UpdateShadowBoxSettingsRequest` is the request for the `UpdateShadowBoxSettings` RPC.
  - `expected_revision` string, int64, nullable: If set, the request fails unless the box is still at this revision. Use the `revision` from `GetShadowBoxStatus` or an earlier response. Set it to fail if the box changed since you read it.
  - `settings` ShadowBoxSettings: Settings that decide what a box covers and how it behaves.
    - `read_policy` ShadowBoxReadPolicy: How the box treats fetches from user topics in its scope.
      - `allow_all_reads` boolean: Lets every consumer keep fetching, so `exempt_principals` has no effect. Defaults to false.
      - `exempt_principals` string[]: Users who can still fetch while the box blocks reads, such as your shadow link's user. An empty name matches clients without SASL or mTLS. An empty list blocks every consumer.
    - `scope` ShadowBoxScope: Resources selected for shadow boxing.
      - `all_resources` AllResources: Selects every resource the box supports. Currently covers user topics, consumer groups, Schema Registry, ACLs, and Roles.
  - `update_mask` string: The settings to change. Settings it doesn't name keep their saved values. Naming `read_policy` replaces the whole read policy, and naming `read_policy.exempt_principals` adds names to the list. If empty, every setting is replaced.

## Response `200`

OK

- UpdateShadowBoxSettingsResponse: `UpdateShadowBoxSettingsResponse` is the response from the `UpdateShadowBoxSettings` RPC.
  - `box` ShadowBox: The shadow box as one broker has installed it.
    - `revision` string, int64: Changes with each `Box`, `Unbox`, or `UpdateShadowBoxSettings` that changes something. Requests that change nothing, and completion, do not change it. `-1` until the first change.
    - `settings` ShadowBoxSettings: Settings that decide what a box covers and how it behaves.
      - `read_policy` ShadowBoxReadPolicy: How the box treats fetches from user topics in its scope.
        - `allow_all_reads` boolean: Lets every consumer keep fetching, so `exempt_principals` has no effect. Defaults to false.
        - `exempt_principals` string[]: Users who can still fetch while the box blocks reads, such as your shadow link's user. An empty name matches clients without SASL or mTLS. An empty list blocks every consumer.
      - `scope` ShadowBoxScope: Resources selected for shadow boxing.
        - `all_resources` AllResources: Selects every resource the box supports. Currently covers user topics, consumer groups, Schema Registry, ACLs, and Roles.
    - `state` 'SHADOW_BOX_STATE_UNBOXED' | 'SHADOW_BOX_STATE_BOXING' | 'SHADOW_BOX_STATE_BOXED' | 'SHADOW_BOX_STATE_UNBOXING': The state of the cluster's shadow box. - SHADOW_BOX_STATE_UNBOXED: No box is requested, and any `Unbox` has completed. - SHADOW_BOX_STATE_BOXING: Some brokers have not yet confirmed the latest change. Every broker counts, including brokers that are down. - SHADOW_BOX_STATE_BOXED: Every broker enforces the latest change and will keep enforcing it after a restart. Writes accepted before the box may still finish, transactions may remain open, and partition offsets may still advance. - SHADOW_BOX_STATE_UNBOXING: `Unbox` was requested, and some brokers have not yet confirmed that they stopped enforcing the box.
    - `state_changed_at` string, date-time, nullable: When `state` last changed, by the clock of the broker that recorded the change. Absent if the cluster has never been boxed or unboxed.

## Other responses

- `400`: A precondition failed, such as a stale expected_revision
- `401`: Unauthenticated.
- `500`: Internal Server Error. Reach out to support.
- `default`: An unexpected error response.

## Changes

- **2026-10-30** `ff1b476fd533`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/redpanda-data/apis/redpanda-cloud-data-plane-api/changes/v1/shadow-box/settings/patch.md)

---

[API](https://skmtc.dev/redpanda-data/apis/redpanda-cloud-data-plane-api.md) - [All operations](https://skmtc.dev/redpanda-data/apis/redpanda-cloud-data-plane-api/llms.txt) - [OpenAPI document](https://skmtc.dev/redpanda-data/apis/redpanda-cloud-data-plane-api/revisions/ff1b476fd533?raw)