---
title: blacklist operations
---

The exact fields each `blacklist.*` 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](/docs/ja/reference/http-api#request) its namespace and agent; see [identities and namespaces](/docs/ja/concepts/identities-and-namespaces). The [operations index](/docs/ja/reference/operations) explains role, kind and the MCP `all` listing. Unknown input fields are served and named in `ignored_args`.

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

## `blacklist.add`

Refuse future memory writes whose value matches a pattern.

`POST /v1/blacklist.add` · MCP `loom_blacklist_add` · role `writer` · idempotent · audited

| Input field | Type | Default | Meaning |
| --- | --- | --- | --- |
| `org` | `str` | required | The tenant (first element of the identity tuple). |
| `namespace` | `str` | required | The namespace the op reads or writes. |
| `pattern` | `str` | required | The text to refuse, matched case-sensitively against a stored value: as a substring, or as a regex of at most 256 characters. |
| `pattern_type` | `Literal['substring', 'regex']` | `'substring'` | `substring` (plain text) or `regex` (RE2, on writes and in the sweep; bounded at add). |
| `scope` | `Literal['namespace', 'org', 'global']` | `'namespace'` | Reach: `namespace` (this one), `org` (every namespace; needs org admin) or `global` (every tenant; needs platform admin). |
| `reason` | `str` | `''` | Why the pattern exists; stored and listed. |
| `created_by` | `str` | `''` | Author recorded only when the call has no authenticated principal to stamp. |
| `sweep` | `bool` | `False` | Also tombstone the live rows the pattern already matches: inside this org, and inside the namespace for a namespace-scoped pattern. |

| Output field | Type | Meaning |
| --- | --- | --- |
| `pattern_id` | `str` | The new pattern's id, for `blacklist.sweep` and `blacklist.remove`. |
| `created_at` | `datetime` | When the pattern was stored (UTC). |
| `swept` | `int` | Rows the sweep tombstoned; 0 without `sweep`. |
| `swept_truncated` | `bool` | True when more rows matched than one sweep takes; call `blacklist.sweep`. |
| `sweep_error` | `str` | "" when the sweep finished, else why not (the pattern is stored either way): `<code>: <message>` (rerun with blacklist.sweep), RE2's reason when a regex cannot run (no query ran), or the kind of error the match query failed with. |

## `blacklist.list`

List patterns that suppress memory storage.

`POST /v1/blacklist.list` · MCP `loom_blacklist_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). |
| `namespace` | `str` | required | The namespace the op reads or writes. |
| `scope` | `Literal['namespace', 'org', 'global'] \| None` | `None` | scope=None returns every pattern that applies to this (org, namespace), which includes higher-scoped (org-wide, global) patterns too — the effective rule set, not just the ones literally pinned to this scope. |
| `limit` | `int` | `100` | At most this many patterns, 1-1000, newest first. |

| Output field | Type | Meaning |
| --- | --- | --- |
| `rows` | `list[_BlacklistRow]` | The live patterns that match the scope filter, newest first. |

## `blacklist.remove`

Remove a previously-added blacklist pattern.

`POST /v1/blacklist.remove` · MCP `loom_blacklist_remove` · role `admin` · idempotent · audited · not listed under the MCP `all` toolset

| Input field | Type | Default | Meaning |
| --- | --- | --- | --- |
| `org` | `str` | required | The tenant (first element of the identity tuple). |
| `pattern_id` | `str` | required | The pattern to tombstone; a namespace pattern outside the caller's reach answers `removed=false`. |
| `removed_by` | `str` | `''` | Recorded on the blacklist cache's version marker only, not on the pattern row. |
| `reason` | `str` | `''` | Accepted but not stored. |

| Output field | Type | Meaning |
| --- | --- | --- |
| `removed` | `bool` | False when no live pattern with that id is visible to the caller. |
| `removed_at` | `datetime \| None` | When the pattern was tombstoned (UTC); null when nothing was removed. |

## `blacklist.sweep`

Tombstone the live rows an existing pattern matches.

`POST /v1/blacklist.sweep` · MCP `loom_blacklist_sweep` · role `writer` · idempotent · audited · not listed under the MCP `all` toolset

| Input field | Type | Default | Meaning |
| --- | --- | --- | --- |
| `org` | `str` | required | The tenant (first element of the identity tuple). |
| `namespace` | `str` | required | The namespace the op reads or writes. |
| `pattern_id` | `str` | required | The live pattern to sweep with; an unknown id or one outside the caller's reach answers 404. |

| Output field | Type | Meaning |
| --- | --- | --- |
| `pattern_id` | `str` | The pattern swept with, echoed. |
| `matched` | `int` | Live rows the pattern matched in this call: at most 5,000 in ClickHouse, plus, under the Postgres authority, the parked heads this call tombstoned. |
| `tombstoned` | `int` | Rows this call tombstoned. |
| `truncated` | `bool` | True when more rows matched than one call takes; call again. |
| `error` | `str` | "" when the sweep finished, else `<code>: <message>` once rows may have landed (call again), RE2's reason when a regex cannot run (no query ran), or the kind of error the match query failed with; a failure before that is the call's. |

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