inbox operations

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

inbox.list

Inboxes the caller may see: those owned by namespace (the authorized namespace) plus, with mine_everywhere, every inbox in the org the caller may post to: one whose owner namespace the caller…

POST /v1/inbox.list · MCP loom_inbox_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.
agent	str	'-'	The writing or reading agent; '-' or '*' means any agent where the op allows it.
mine_everywhere	bool	False	Also list every org inbox the caller may post to (write on its owner namespace, or listed as a poster); false lists only inboxes owned by namespace.
limit	int	200	At most this many inbox rows are read, 1-500 (with mine_everywhere, before the visibility filter).

Output field	Type	Meaning
inboxes	list[InboxPayload]	The visible inboxes, ordered by name.

inbox.policy_list

List an inbox's trust policies.

POST /v1/inbox.policy_list · MCP loom_inbox_policy_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.
agent	str	'-'	The writing or reading agent; '-' or '*' means any agent where the op allows it.
inbox	str	required	The inbox whose rules to list; one the caller cannot read answers 404.

Output field	Type	Meaning
policies	list[PolicyPayload]	Every live rule of the inbox, ordered by poster then kind.

inbox.policy_set

Set the trust mode an inbox owner chose for a poster and task kind (Loom stores it, never changes it).

POST /v1/inbox.policy_set · MCP loom_inbox_policy_set · 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).
namespace	str	required	The namespace the op reads or writes.
agent	str	'-'	The writing or reading agent; '-' or '*' means any agent where the op allows it.
inbox	str	required	The inbox the rule belongs to; the caller must be an admin of its owner namespace.
poster	str	required	Whom the rule covers: a subject, an agent label, or * for every poster.
kind	str	'*'	The task kind the rule covers; * covers every kind.
mode	Literal['deny', 'review', 'auto']	required	deny refuses the post (403), review lands it in triage, auto lands it todo.
require_evidence	list[str]	(computed)	Brief fields that must be present (a shape check at create), e.g. ["inputs.finding_id"].
remove	bool	False	True deletes the (poster, kind) rule instead of setting it.

Output field	Type	Meaning
policy	PolicyPayload \| None	The rule as stored; null when remove deleted it.
removed	bool	True when the rule was deleted.

inbox.principals

The identities loom already knows in the org — the poster picker's source.

POST /v1/inbox.principals · MCP loom_inbox_principals · role admin · idempotent · 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.
agent	str	'-'	The writing or reading agent; '-' or '*' means any agent where the op allows it.
inbox	str	required	The inbox whose posters are marked listed; an unregistered or unreadable name answers against namespace with nobody listed.
query	str	''	Case-insensitive substring matched against subject and label; "" returns everyone.
limit	int	200	At most this many principals, 1-500; truncated says more matched.

Output field	Type	Meaning
principals	list[Principal]	People first, then service accounts, then others, each sorted by label.
truncated	bool	True when more principals matched than limit.

inbox.register

namespace is the owner namespace (the caller must be its admin).

POST /v1/inbox.register · MCP loom_inbox_register · 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).
namespace	str	required	The namespace the op reads or writes.
agent	str	'-'	The writing or reading agent; '-' or '*' means any agent where the op allows it.
inbox	str	required	The inbox name, unique in the org; registering an existing name edits its settings.
owner_agent	str	required	The agent that works the inbox: a pull or claim naming no agent claims as it.
description	str	''	Free text shown with the inbox; Loom does not interpret it.
posters	list[str]	(computed)	Subjects allowed to post besides writers on the owner namespace; an agent label here admits only a caller without a token.
accept_disclosure	list[Literal['confidential', 'internal', 'public_ok']]	(computed)	The disclosure levels a task may carry to land here; a create or reassign with any other level is refused (422).
default_lease_seconds	int	1800	Seconds a claim or heartbeat holds the lease when the call names no lease_seconds.
max_attempts	int	3	Expired leases a task may reach; after that the sweeper blocks it on a human instead of returning it to todo.
max_defers	int	5	Defers a task may take; the next task.defer blocks it on a human instead.
triage_escalate_after_seconds	int	14400	Seconds a task may wait in triage before the sweeper records one triage_escalated event on it.
webhook_url	str	''	Where signed wake-up notices (event kinds and task ids, never task text) are POSTed: an http(s) URL on a public host (checked again at each delivery); "" sends none.
webhook_secret_ref	str	''	Name of the environment variable holding the webhook signing secret (never stored): LOOM_WEBHOOK_SECRET_<ORG>__<NAME>, ORG the org id with a-z upper-cased, digits kept and any other byte as _ and two hex digits (acme-corp →…
if_match_version	int \| None	None	The inbox version this edit was based on; a different current version answers 409.

Output field	Type	Meaning
inbox	InboxPayload	The inbox as written.
created	bool	True when this call registered a new inbox; false for a settings edit.