---
title: "Unbox the cluster"
method: POST
path: "/v1/shadow-box/unbox"
tags: ["Shadow Box"]
---

# Unbox the cluster

`POST /v1/shadow-box/unbox`

## Request

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

Release the shadow box. The saved settings stay for the next box.

## Request body

- UnboxRequest: `UnboxRequest` is the request for the `Unbox` 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.

## Response `200`

OK

- UnboxResponse: `UnboxResponse` is the response from the `Unbox` 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/unbox/post.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)