---
title: "Admin team management — preview or execute a workspace teardown (audit-logged)"
method: POST
path: "/api/v1/admin/teams/{team_id}/deletion"
tags: ["admin"]
---

# Admin team management — preview or execute a workspace teardown (audit-logged)

`POST /api/v1/admin/teams/{team_id}/deletion`

## Request

- Base URL: `https://api.badgeia.com`
- URL: `https://api.badgeia.com/api/v1/admin/teams/{team_id}/deletion`
- Auth: none declared

Preview (default) or execute a workspace teardown.

POST, not DELETE, for the same reason as `POST /admin/support/erasure`: the
ceremony needs a request body, and the safe default — a dry run that
computes what WOULD happen — must not be spelled with a destructive verb.

Dry run (default) returns the counts-only inventory: how many agents get
reassigned to the owner, how many of those hold provider credentials that
will be cleared, how many memberships and invitations are dropped, how many
workspace radar presets die, and how many historical runs are left with a
dangling `team_id`.

Execute reassigns the workspace agents to the OWNER's personal scope,
revokes their workspace machine credentials, clears their provider
credentials, and deletes the team with its memberships, invitations, and
presets — all in one transaction with the audit row.

**Member user accounts are never deleted.** Removing a workspace removes
access, not people.

Auth: anonymous → 401, non-admin → 403, admin → 200. Flag-off → 404.
404 when the team doesn't exist.
409 when a confirmation no longer matches the live workspace, or when the
team has no resolvable owner to reassign its agents to.
422 when the execute body is incomplete (see `AdminTeamDeletionRequest`).

## Path parameters

- `team_id` string, uuid, required

## Request body

- AdminTeamDeletionRequest: Body for POST /admin/teams/{team_id}/deletion. Deleting a team reassigns its workspace agents to the owner's personal scope and removes every membership, so the body is an attestation, not a trigger — the PRD-025 contract (`AdminSupportErasureRequest`) applied to a destructive tenant operation: • `dry_run` defaults to TRUE. An empty POST previews and never deletes. • Execute requires the team's name typed back exactly. A name is a deliberate act to reproduce; a button is a reflex. • Execute requires the member and agent counts the operator just read. A stale preview — a member accepted an invitation in the meantime — 409s instead of silently deleting something larger than was reviewed. • `acknowledge_agent_reassignment` states the surprising consequence in words, mirroring `source_mailbox_purged`, so a half-built or replayed request body cannot delete. `confirm_name` is compared to the live team name in the handler and is never echoed back, logged, or written to the audit `detail`.
  - `dry_run` boolean
  - `confirm_name` string, nullable
  - `expected_member_count` integer, nullable
  - `expected_agent_count` integer, nullable
  - `acknowledge_agent_reassignment` boolean

## Response `200`

Successful Response

- object

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/badgeia/apis/badge.md) · [All operations](https://skmtc.dev/badgeia/apis/badge/llms.txt) · [OpenAPI document](https://skmtc.dev/badgeia/apis/badge/revisions/7e7f7fee8b77?raw)