erasure operations
The exact fields each erasure.* operation takes and returns.
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 its namespace and agent; see identities and namespaces. The operations index explains role, kind and the MCP all listing. Unknown input fields are served and named in ignored_args.
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. |