workspaces

Archive a workspace

Archive the workspace and its whole subtree: a tree with an archived root and live children is not what a caller asking to archive a workspace meant.

Every node stays readable, and each one is renamed to <name>-<id tail> — so the bare handle is free for reuse the moment the archive commits, and the archived row is still addressable under the name it now displays.

That moves the workspace's marketplace plugin path, which is the cost of releasing the handle: an archived workspace should not keep holding a name a live one wants.

Two things an archive does that a delete does not, both because archived is a live status here:

  • the access the workspace granted is kept. Releasing it would leave a readable workspace nobody can read, which is a delete wearing an archive's name.
  • deleted_by/deleted_at are not stamped. They belong to a tombstone, and an archived workspace is not one.

A personal or org_default workspace cannot be archived, for the same reason it cannot be deleted: it is provisioning identity, and an account with no tree root has nothing to create in.

Idempotent, per node: archived_count is what this call changed, so a re-archive is 200 with 0.

A re-archive re-runs the cascade. If a cascade is still pending or running, the call answers with that run as cascade_run_id and starts nothing. Otherwise it records the next attempt — which is how a cascade that failed on a refused hook is finished once the refusal is resolved — and that run acts as the caller, who becomes the workspace's recorded archiver if they were not already.

The subtree is collected from a receipted read. A live descendant the caller cannot see is neither archived around (it would stay live under an archived parent, its contents never cascaded) nor archived through (that touches rows the caller was never shown): the archive is refused with 409 workspace_subtree_unseen, naming only how many, and succeeds once those workspaces' own admins have archived them.

post/registry/v1/workspaces/{workspace_id}/archive

Request

  • Base URL: https://api.atlan.com (the document declares no server; this is the origin it was published from)
  • URL: https://api.atlan.com/registry/v1/workspaces/{workspace_id}/archive
  • Auth: HTTP bearer

Path parameters

workspace_idstring required

Workspace handle (workspace_…) or the workspace's kebab-case name. The two grammars are disjoint, so no disambiguation is needed. A name is mutable — a display_name edit re-derives it — so a client that stores an address should store the handle, which every response echoes.

Response

OK

archived_countinteger required

How many nodes this call changed. 0 on a re-archive.

cascade_run_idstring required

The action run cascading the archive over the subtree's artifacts, projects and repos.

The workspace rows are archived synchronously — they are a handful of rows and the caller asked for them — but their contents can be thousands of artifacts, each with an archive.pre hook that may refuse. That is a run, not a request: poll GET /action-runs/{cascade_run_id} for its status and …/jobs for the per-item report, which names anything that refused and why.

On a re-archive: the cascade still in flight if there is one, otherwise the next attempt.

idstring required

Stable identifier of this resource.

subtree_sizeinteger required

How many nodes the subtree had, as the caller's receipted read saw it. Reported beside archived_count because the two differing is meaningful: it means some nodes were already archived, not that any were missed.

workspace_statusstring required

Always archived, echoed so a client need not assume it.

Changes

No recorded changes to this operation across all 1 revision of this API.