---
title: learnings operations
---

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

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

## `learnings.list`

List learnings candidates by status (pending by default, promoted, rejected).

`POST /v1/learnings.list` · MCP `loom_learnings_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. |
| `status` | `Literal['pending', 'promoted', 'rejected'] \| None` | `None` | None = pending |
| `limit` | `int` | `50` | At most this many candidates, 1-500, newest proposal first. |
| `source_kind` | `str \| None` | `None` | None = all seeders |

| Output field | Type | Meaning |
| --- | --- | --- |
| `rows` | `list[_LearningEntry]` | Candidates with the requested status in `namespace`, newest proposal first. |

## `learnings.quality`

Per-namespace approve-ratio rollup of the learnings queue.

`POST /v1/learnings.quality` · MCP `loom_learnings_quality` · 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 \| None` | `None` | None = org-wide rollup |
| `source_kind` | `str \| None` | `'conversation_seeder'` | Only candidates from this producer; None counts every producer. |

| Output field | Type | Meaning |
| --- | --- | --- |
| `rows` | `list[LearningsQualityRow]` | One row per namespace the caller may see, most pending first; empty without access. |

## `learnings.review`

Approve or reject a pending learning.

`POST /v1/learnings.review` · MCP `loom_learnings_review` · 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. |
| `candidate_id` | `str` | required | The queued candidate to decide; one unknown in `namespace` answers 404. |
| `decision` | `Literal['promote', 'reject']` | required | `promote` writes it to `destination` and marks it promoted; `reject` only marks it rejected. |
| `reason` | `str` | `''` | Why; stored as `decision_reason` and carried into the promoted row's provenance. |
| `destination` | `Literal['memory', 'knowledge', 'both'] \| None` | `None` | Where a promotion lands: 'memory', 'knowledge' or 'both', but query_history and knowledge_gap drafts allow only 'memory'; unset is 'knowledge' for an assistant_turn rule and 'memory' otherwise. |
| `approver` | `str` | `'learnings-reviewer'` | Promotion label for other candidates (default 'learnings-reviewer'); query_history and knowledge_gap use the authenticated actor instead, and the audit subject always records the authenticated actor. |

| Output field | Type | Meaning |
| --- | --- | --- |
| `candidate_id` | `str` | The candidate, echoed. |
| `new_status` | `Literal['pending', 'promoted', 'rejected']` | The status the candidate holds after this call. |
| `promoted_to_shared` | `bool` | True when this call wrote memory: `loom.shared` for a supporters candidate, a namespace row for a seeder, the agent's `user_id` '-' row for a bot's rule. |
| `promoted_to_knowledge` | `bool` | True when this call upserted the candidate as a knowledge document. |
| `knowledge_source_uri` | `str` | source_uri the knowledge doc was upserted under (for later knowledge.delete). |
| `decided_at` | `datetime` | When this call ran (UTC), also on a repeat that changed nothing. |

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