---
title: inbox operations
---

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

## `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. |

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