---
title: "Destroy a RETAINED onion identity (irreversible)"
method: POST
path: "/platform/deployments/{id}/onion/purge"
tags: ["Platform"]
---

# Destroy a RETAINED onion identity (irreversible)

`POST /platform/deployments/{id}/onion/purge`

## Request

- Base URL: `https://api.imprezahost.com/v1`
- URL: `https://api.imprezahost.com/v1/platform/deployments/{id}/onion/purge`
- Auth: API key in header `X-API-Key` and API key in header `X-API-Secret`

Destroys every parked recovery copy of one address on the
deployment's host and releases the platform-side reservation.
Agent success confirms deletion of retained copies on the current host.
Prior exports and external backups remain outside this operation.
Release mode clears records only and does not verify key deletion. The address must be a RETAINED identity of
this deployment: a prior address left by a rotation, or the
deployment's own stale address when it is already uninstalled
(that case is released synchronously, `mode: released`). The
CURRENT address of a live deployment is refused. Requires
`manage`, `confirm: true` and `confirm_address` verbatim. Agent
mode needs an agent announcing `onion-purge-v1` (202); release
mode answers 200 with no agent command.

## Path parameters

- `id` string, required

## Request body

- object
  - `confirm` true, required
  - `confirm_address` string, required: The RETAINED .onion address being destroyed, verbatim.

## Response `200`

Release mode — control-plane records cleared synchronously (uninstalled deployment).

## Other responses

- `202`: Agent mode — purge command enqueued; the reservation is released when the agent reports success.
- `400`: Confirmation missing/invalid, or the address is the deployment's CURRENT address.
- `401`: Invalid or missing API credentials
- `404`: Resource not found
- `409`: A purge is already pending for this deployment.
- `422`: Agent does not announce onion-purge-v1.

---

[API](https://skmtc.dev/imprezahost/apis/impreza-host-public-api.md) · [All operations](https://skmtc.dev/imprezahost/apis/impreza-host-public-api/llms.txt) · [OpenAPI document](https://skmtc.dev/imprezahost/apis/impreza-host-public-api/revisions/db86511f604f?raw)