blacklist operations

The exact fields each blacklist.* 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.

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.