docs: how to permanently prune a Team / Workspace / Project / Dataset

[tonybart1337]

New page: Permanent removal (data-organization/storage/permanent-removal.md), nested under Disk usage & Cleanup in SUMMARY.md.

Documents the two-step removal model added in supervisely/issues#5973 (server: internal MR !1853, SDK: supervisely/supervisely#1779).

What it covers

• The model — *.archive (soft, reversible, any user with permission) → *.remove.permanently (hard, root only, rejects anything not archived), at all four levels.
• API reference table — request body and return value for each of the nine methods, including the new teams.remove.permanently, workspaces.remove.permanently and instance.data.cleanup-unused.
• The async contract — team and workspace removal return a taskId and drain in the background; poll tasks.info; a failure reaches a terminal error rather than retrying forever.
• Two-wave reclamation — the section that most needs writing down (below).
• A worked example — archive → remove → poll → trigger the GC, with cURL and Python SDK tabs.
• Notes — admin team (id 1) is protected, permanent removal is idempotent, and preserveProjectCard: true is a different operation that keeps the project card and does not require an archived project.

Why the reclamation section matters

Image data is instance-global and reference-counted by content hash, so permanently removing an entity drops its references, not the objects. Bucket usage therefore does not fall to its final value the moment a removal finishes: wave 1 reclaims inline past the 12-hour REMOVE_IMAGE_REQUESTED_THRESHOLD, wave 2 is the GC with a 3-day grace window. Stated plainly here, because otherwise the expected behaviour reads as a bug and generates support tickets.

Conventions

Followed what the repo actually does rather than what SKILL.md says where they differ: {% hint %} and {% tabs %} are widely used, {% stepper %} is documented but used by zero pages, so the how-to steps are plain ### Step N headings like server-cleanup.md and server-trash-bin.md. Front matter is description only, matching the ~57 pages that have any.

This is the first page with raw cURL against /public/api/v3/; every other page delegates REST to api.docs.supervisely.com and shows Python SDK. I gave both, and linked out to the API reference.

Two things for the reviewer

1. The Python tabs for team/workspace use api.post("teams.archive", ...) because the dedicated SDK methods are still in review (feat(api): archive + permanent removal for teams and workspaces supervisely#1779). Once that lands they can become api.team.archive(...) / api.team.remove_permanently(...) / api.cleanup_unused_data().
2. There's a warning hint about a genuine footgun: the SDK already has an unrelated api.project.archive(id, archive_url) that offloads a project to an external backup archive. It collides by name with the new projects.archive soft-delete and would mislead anyone reading this page next to the SDK reference.

🤖 Generated with Claude Code