---
title: erasure operations
---

The exact fields each `erasure.*` operation takes and returns.

<!-- Generated by `python scripts/codegen/docs_reference.py` from the op registry; edit the models, not this page. -->

Every op is `POST /v1/<op>` over HTTP and the MCP tool `loom_<op>`. The identity fields (`org`, `namespace`, `agent`, `user_id`, `session_id`) are filled from the token and the MCP session when a transport can; for an HTTP call with no token on a single-user server, the install's org on every op but `code.*` and `tracker.*` (which keep their plane's), and on [some ops](/ja/reference/http-api#request) its namespace and agent; see [identities and namespaces](/ja/concepts/identities-and-namespaces). The [operations index](/ja/reference/operations) explains role, kind and the MCP `all` listing. Unknown input fields are served and named in `ignored_args`.

<!-- prettier-ignore-start -->

## `erasure.export`

Export the rows about a user or namespace, each section capped at `section_limit`.

`POST /v1/erasure.export` · MCP `loom_erasure_export` · role `admin` · idempotent · audited

| Input field | Type | Default | Meaning |
| --- | --- | --- | --- |
| `org` | `str` | required | The tenant (first element of the identity tuple). |
| `scope_type` | `Literal['user_id', 'namespace', 'namespace_list']` | required | `user_id` exports one user's rows across the org (org admin only); `namespace` exports one namespace (admin on it). |
| `scope_value` | `str` | required | The user id or namespace to export; never a mirror's name (`acl-` and 24 hex digits). |
| `requester` | `str` | required | email or service account requesting the export |
| `include_tombstoned` | `bool` | `True` | Include tombstoned memory and conversation rows. |
| `section_limit` | `int` | `10000` | Per-section caps. |

| Output field | Type | Meaning |
| --- | --- | --- |
| `exported_at` | `datetime` | When the export was read (UTC). |
| `org` | `str` | The tenant (first element of the identity tuple). |
| `scope_type` | `Literal['user_id', 'namespace', 'namespace_list']` | Echo of the requested scope kind. |
| `scope_value` | `str` | Echo of the requested user id or namespace. |
| `requester` | `str` | Echo of who asked for the export. |
| `counts` | `dict[str, int]` | Rows returned per section (`memory`, `knowledge`, `conversations`, `conversation_threads`, `agent_events`, `audit_log`): at most `section_limit`, and the section's `truncated` says more exist. |
| `memory` | `ErasureExportSection` | `loom.memory` rows in scope (under the Postgres authority, its heads); tombstoned rows too when `include_tombstoned`. |
| `knowledge` | `ErasureExportSection` | Knowledge chunk rows of the namespace, or every one the user wrote for a `user_id` scope. |
| `conversations` | `ErasureExportSection` | Turns and saved messages in scope with their `sensitivity`, up to `erasure_export_conversation_max_bytes` of text plus the turn that crosses it. |
| `conversation_threads` | `ErasureExportSection` | Threads in scope with their title, metadata and `sensitivity`, capped by `section_limit` rows only (no byte budget). |
| `agent_events` | `ErasureExportSection` | Per-request ledger rows in scope, newest first. |
| `audit_log` | `ErasureExportSection` | Audit rows in scope; for `user_id`, rows whose subject mentions the user id. |

## `erasure.list`

Audit-shaped roll-up of the org's erasures the caller may see: the org-wide view for an org admin, the namespace sagas of the caller's own namespaces otherwise.

`POST /v1/erasure.list` · MCP `loom_erasure_list` · role `viewer` · read · not listed under the MCP `all` toolset

| Input field | Type | Default | Meaning |
| --- | --- | --- | --- |
| `org` | `str` | required | The tenant (first element of the identity tuple). |
| `limit` | `int` | `50` | At most this many sagas, newest first; the server caps it at 500. |
| `status` | `Literal['in_progress', 'completed', 'failed'] \| None` | `None` | filter to one status if needed |

| Output field | Type | Meaning |
| --- | --- | --- |
| `rows` | `list[ErasureListRow]` | Recent sagas, newest first: org-wide for an org admin, otherwise only `namespace` sagas on namespaces the caller belongs to. |

## `erasure.request`

Erase the rows about a user or namespace (the audit trail is kept).

`POST /v1/erasure.request` · MCP `loom_erasure_request` · role `writer` · idempotent · audited

| Input field | Type | Default | Meaning |
| --- | --- | --- | --- |
| `org` | `str` | required | The tenant (first element of the identity tuple). |
| `scope_type` | `Literal['user_id', 'namespace', 'namespace_list']` | required | What `scope_value` names: `user_id` (one user across the org's namespaces, org admin only), `namespace` (one namespace, admin on it) or `namespace_list` (several, org admin only). |
| `scope_value` | `str` | required | The user id, namespace or (for `namespace_list`) a JSON array of 1–500 names or {"namespaces": [...], "purge": bool}; only a platform admin with auth on may name a mirror (`acl-` and 24 hex digits). |
| `requester` | `str` | required | email or service account that requested the erasure |
| `urgency` | `Literal['normal', 'urgent']` | `'normal'` | `normal` or `urgent`; recorded on the saga's ledger row, the saga runs the same either way. |
| `purge` | `bool` | `False` | Hard-delete the rows of the soft-delete tables (memory, embeddings, chunks, documents, summaries, links) instead of stamping tombstoned_at: a tombstone keeps the bytes in every FINAL read and merge; a purge takes them out of the parts. |
| `external` | `bool` | `True` | External backends (Langfuse traces by tag, ClickStack OTel rows, …) run for every namespace of the scope and fail the saga closed. |

| Output field | Type | Meaning |
| --- | --- | --- |
| `erasure_id` | `str` | Id of the saga; pass it to `erasure.status`. |
| `status` | `Literal['in_progress', 'completed', 'failed']` | `completed`, or `failed` when a step or the residue check failed; the recovery worker retries a failed saga. |
| `steps` | `list[_ErasureStepResult]` | Per-step row counts; empty for a withheld mirror receipt, disclosing no failed stage. |
| `requested_at` | `datetime` | When the saga was registered (UTC). |
| `completed_at` | `datetime \| None` | When the saga reached its terminal state (UTC); `None` while it runs. |
| `residue_count` | `int` | Live residue count; zero for a withheld mirror receipt, so zero alone does not prove absence. |
| `residue` | `dict[str, int]` | Nonzero live counts by substrate; `{}` for a withheld mirror receipt does not prove absence. |
| `verified_at` | `datetime \| None` | Census completion time (UTC), or `None` when incomplete, never run or withheld; only status/list to a flat platform admin expose marked evidence. |
| `census` | `dict[str, int] \| None` | Complete census counts including zeros, or `None` when unavailable or withheld. |
| `purge` | `bool` | The scope's delete-or-tombstone mode (a single namespace's is tombstone whatever was asked); a scope that holds a mirror is deleted whatever this says. |
| `failure_reason` | `str` | Failure reason, or `""` on success; withheld mirror receipts use `ERASURE_FAILED` for every cause. |
| `steps_completed` | `list[str]` | Names of the steps finished so far, sorted; empty for a withheld mirror receipt. |

## `erasure.status`

Check the status of an in-flight erasure request (queued, running, completed, failed).

`POST /v1/erasure.status` · MCP `loom_erasure_status` · role `viewer` · read · not listed under the MCP `all` toolset

| Input field | Type | Default | Meaning |
| --- | --- | --- | --- |
| `erasure_id` | `str` | required | Id returned by `erasure.request`. |

| Output field | Type | Meaning |
| --- | --- | --- |
| `found` | `bool` | False for an unknown id and for a saga the caller may not read (the two look alike). |
| `erasure_id` | `str` | The saga id asked about. |
| `org` | `str \| None` | The tenant (first element of the identity tuple). |
| `scope_type` | `str \| None` | The saga's scope kind (`user_id`, `namespace` or `namespace_list`); `None` when not found. |
| `scope_value` | `str \| None` | The saga's scope (user id, namespace, or the JSON list); a list leaves out any mirror's name but for a platform admin. |
| `requester` | `str \| None` | Who asked for the erasure, as given in the request. |
| `status` | `Literal['in_progress', 'completed', 'failed'] \| None` | `in_progress`, `completed` or `failed`; `None` when not found. |
| `current_step` | `int \| None` | How many steps have finished; 99 once completed, zero for a withheld mirror receipt. |
| `requested_at` | `datetime \| None` | When the saga was registered (UTC). |
| `completed_at` | `datetime \| None` | When the saga reached its terminal state (UTC); `None` while in progress. |
| `failure_reason` | `str \| None` | Failure reason, or `None` without a failure; withheld mirror receipts use `ERASURE_FAILED` for every cause. |
| `residue_count` | `int` | Live residue count; zero for a withheld mirror receipt, so zero alone does not prove absence. |
| `residue` | `dict[str, int]` | Nonzero live counts by substrate; `{}` for a withheld mirror receipt does not prove absence. |
| `verified_at` | `datetime \| None` | Census completion time (UTC), or `None` when incomplete, never run or withheld; a flat platform admin retains marked evidence. |
| `census` | `dict[str, int] \| None` | Complete census counts including zeros, or `None` when unavailable or withheld. |
| `purge` | `bool` | The scope's delete-or-tombstone mode (a single namespace's is tombstone whatever was asked); a scope that holds a mirror is deleted whatever this says. |

<!-- prettier-ignore-end -->
