<a id="inbox-operations"></a>

# Operações de `inbox`

<!-- i18n: source=docs/reference/operations/inbox.md blob=7a22f85ac9db3798ae3201b9df998d2bc3612534 model=claude-sonnet-5-5 -->
> Esta página é uma tradução automática da [página em inglês](https://github.com/ClickHouse/loom/blob/main/docs/reference/operations/inbox.md), que prevalece.
> Machine-translated from the [English page](https://github.com/ClickHouse/loom/blob/main/docs/reference/operations/inbox.md), which is authoritative.


Os campos exatos que cada operação `inbox.*` recebe e retorna.

<!-- Generated by `python scripts/codegen/docs_reference.py` from the op registry; edit the models, not this page. -->

Toda op é `POST /v1/<op>` via HTTP e a ferramenta MCP `loom_<op>`. Os campos de identidade (`org`, `namespace`, `agent`, `user_id`, `session_id`) são preenchidos a partir do token e da sessão MCP quando o transporte consegue; em uma chamada HTTP sem token em um servidor de usuário único, usa-se a org da instalação em todas as ops, exceto `code.*` e `tracker.*` (que mantêm a org do seu plano), e, em [algumas ops](https://github.com/ClickHouse/loom/blob/main/docs/reference/http-api.md#request), o namespace e o agente; veja [identidades e namespaces](/pt-BR/concepts/identities-and-namespaces). O [índice de operações](https://github.com/ClickHouse/loom/blob/main/docs/reference/operations.md) explica role, kind e a listagem `all` do MCP. Campos de entrada desconhecidos são atendidos e listados em `ignored_args`.

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

<a id="inboxlist"></a>

## `inbox.list`

Inboxes que o chamador pode ver: aquelas pertencentes a ``namespace`` (o namespace autorizado) e, com ``mine_everywhere``, todas as inboxes da organização nas quais o chamador pode postar: uma cujo namespace proprietário o chamador…

`POST /v1/inbox.list` · MCP `loom_inbox_list` · role `viewer` · leitura · não listada no toolset `all` do MCP

| Campo de entrada | Tipo | Padrão | Significado |
| --- | --- | --- | --- |
| `org` | `str` | obrigatório | O tenant (primeiro elemento da tupla de identidade). |
| `namespace` | `str` | obrigatório | O namespace que a op lê ou grava. |
| `agent` | `str` | `'-'` | O agente que grava ou lê; `'-'` ou `'*'` significa qualquer agente quando a op permite. |
| `mine_everywhere` | `bool` | `False` | Lista também todas as inboxes da organização nas quais o chamador pode postar (gravação no namespace proprietário, ou listado como poster); com false, lista apenas as inboxes pertencentes a `namespace`. |
| `limit` | `int` | `200` | No máximo este número de linhas de inbox é lido, de 1 a 500 (com `mine_everywhere`, antes do filtro de visibilidade). |

| Campo de saída | Tipo | Significado |
| --- | --- | --- |
| `inboxes` | `list[InboxPayload]` | As inboxes visíveis, ordenadas por nome. |

<a id="inboxpolicy_list"></a>

## `inbox.policy_list`

Lista as políticas de confiança de uma inbox.

`POST /v1/inbox.policy_list` · MCP `loom_inbox_policy_list` · papel `viewer` · leitura · não listado no toolset `all` do MCP

| Campo de entrada | Tipo | Padrão | Significado |
| --- | --- | --- | --- |
| `org` | `str` | obrigatório | O tenant (primeiro elemento da tupla de identidade). |
| `namespace` | `str` | obrigatório | O namespace que a op lê ou grava. |
| `agent` | `str` | `'-'` | O agente que grava ou lê; `'-'` ou `'*'` significa qualquer agente, onde a op permite. |
| `inbox` | `str` | obrigatório | A inbox cujas regras serão listadas; se o chamador não puder lê-la, a resposta é 404. |

| Campo de saída | Tipo | Significado |
| --- | --- | --- |
| `policies` | `list[PolicyPayload]` | Todas as regras ativas da inbox, ordenadas por poster e depois por kind. |

<a id="inboxpolicy_set"></a>

## `inbox.policy_set`

Define o modo de confiança que o dono de uma inbox escolheu para um autor de postagens e um tipo de tarefa (o Loom armazena o valor, nunca o altera).

`POST /v1/inbox.policy_set` · MCP `loom_inbox_policy_set` · role `admin` · idempotente · auditado · não listado no toolset `all` do MCP

| Campo de entrada | Tipo | Padrão | Significado |
| --- | --- | --- | --- |
| `org` | `str` | obrigatório | O tenant (primeiro elemento da tupla de identidade). |
| `namespace` | `str` | obrigatório | O namespace que a op lê ou grava. |
| `agent` | `str` | `'-'` | O agente que grava ou lê; `'-'` ou `'*'` significa qualquer agente, onde a op permitir. |
| `inbox` | `str` | obrigatório | A inbox à qual a regra pertence; quem chama deve ser admin do namespace dono dela. |
| `poster` | `str` | obrigatório | Quem a regra cobre: um subject, um rótulo de agente ou `*` para todos os autores de postagens. |
| `kind` | `str` | `'*'` | O tipo de tarefa que a regra cobre; `*` cobre todos os tipos. |
| `mode` | `Literal['deny', 'review', 'auto']` | obrigatório | `deny` recusa a postagem (403), `review` a coloca em `triage`, `auto` a coloca em `todo`. |
| `require_evidence` | `list[str]` | *(calculado)* | Campos do brief que devem estar presentes (uma verificação de formato na criação), por exemplo ["inputs.finding_id"]. |
| `remove` | `bool` | `False` | True exclui a regra (poster, kind) em vez de defini-la. |

| Campo de saída | Tipo | Significado |
| --- | --- | --- |
| `policy` | `PolicyPayload \| None` | A regra como armazenada; null quando `remove` a excluiu. |
| `removed` | `bool` | True quando a regra foi excluída. |

<a id="inboxprincipals"></a>

## `inbox.principals`

As identidades que o loom já conhece na organização — a fonte do seletor de remetentes.

`POST /v1/inbox.principals` · MCP `loom_inbox_principals` · papel `admin` · idempotente · não listado no toolset `all` do MCP

| Campo de entrada | Tipo | Padrão | Significado |
| --- | --- | --- | --- |
| `org` | `str` | obrigatório | O tenant (primeiro elemento da tupla de identidade). |
| `namespace` | `str` | obrigatório | O namespace que a op lê ou grava. |
| `agent` | `str` | `'-'` | O agente que grava ou lê; `'-'` ou `'*'` significa qualquer agente quando a op permite. |
| `inbox` | `str` | obrigatório | A inbox cujos remetentes são marcados como `listed`; um nome não registrado ou ilegível é respondido em relação a `namespace`, sem ninguém listado. |
| `query` | `str` | `''` | Substring sem distinção entre maiúsculas e minúsculas, comparada com o subject e o label; "" retorna todos. |
| `limit` | `int` | `200` | No máximo esta quantidade de principals, de 1 a 500; `truncated` indica que houve mais correspondências. |

| Campo de saída | Tipo | Significado |
| --- | --- | --- |
| `principals` | `list[Principal]` | Primeiro pessoas, depois contas de serviço, depois os demais, cada grupo ordenado por label. |
| `truncated` | `bool` | True quando mais principals corresponderam do que `limit`. |

<a id="inboxregister"></a>

## `inbox.register`

``namespace`` é o namespace proprietário (quem chama precisa ser o administrador dele).

`POST /v1/inbox.register` · MCP `loom_inbox_register` · papel `admin` · idempotente · auditado · não listado no toolset `all` do MCP

| Campo de entrada | Tipo | Padrão | Significado |
| --- | --- | --- | --- |
| `org` | `str` | obrigatório | O tenant (primeiro elemento da tupla de identidade). |
| `namespace` | `str` | obrigatório | O namespace que a op lê ou grava. |
| `agent` | `str` | `'-'` | O agente que grava ou lê; `'-'` ou `'*'` significa qualquer agente onde a op permitir. |
| `inbox` | `str` | obrigatório | O nome da inbox, único na org; registrar um nome existente edita suas configurações. |
| `owner_agent` | `str` | obrigatório | O agente que trabalha a inbox: um pull ou claim sem `agent` faz o claim como ele. |
| `description` | `str` | `''` | Texto livre exibido com a inbox; o Loom não o interpreta. |
| `posters` | `list[str]` | *(calculado)* | Subjects autorizados a postar, além dos writers do namespace proprietário; um rótulo de agente aqui admite apenas quem chama sem token. |
| `accept_disclosure` | `list[Literal['confidential', 'internal', 'public_ok']]` | *(calculado)* | Os níveis de `disclosure` que uma tarefa pode ter para chegar aqui; um create ou reassign com qualquer outro nível é recusado (422). |
| `default_lease_seconds` | `int` | `1800` | Segundos que um claim ou heartbeat mantém o lease quando a chamada não informa `lease_seconds`. |
| `max_attempts` | `int` | `3` | Leases expirados que uma tarefa pode atingir; depois disso o sweeper a bloqueia em um humano em vez de devolvê-la a `todo`. |
| `max_defers` | `int` | `5` | Defers que uma tarefa pode receber; o próximo `task.defer` a bloqueia em um humano. |
| `triage_escalate_after_seconds` | `int` | `14400` | Segundos que uma tarefa pode esperar em `triage` antes de o sweeper registrar nela um evento `triage_escalated`. |
| `webhook_url` | `str` | `''` | Para onde são enviados por POST avisos de despertar assinados (tipos de evento e ids de tarefa, nunca o texto da tarefa): uma URL http(s) em um host público (verificada de novo a cada entrega); "" não envia nenhum. |
| `webhook_secret_ref` | `str` | `''` | Nome da variável de ambiente que guarda o segredo de assinatura do webhook (nunca armazenado): `LOOM_WEBHOOK_SECRET_<ORG>__<NAME>`, ORG é o id da org com a-z em maiúsculas, dígitos mantidos e qualquer outro byte como `_` e dois dígitos hex (`acme-corp` →… |
| `if_match_version` | `int \| None` | `None` | A `version` da inbox em que esta edição se baseou; uma versão atual diferente responde 409. |

| Campo de saída | Tipo | Significado |
| --- | --- | --- |
| `inbox` | `InboxPayload` | A inbox como gravada. |
| `created` | `bool` | True quando esta chamada registrou uma inbox nova; false para uma edição de configurações. |

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