---
title: ops operations
---

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

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

## `ops.capabilities`

Identity is optional: a client discovers the surface with whatever token it holds (role check only; no namespace is addressed).

`POST /v1/ops.capabilities` · MCP `loom_ops_capabilities` · role `viewer` · read

| Input field | Type | Default | Meaning |
| --- | --- | --- | --- |
| `org` | `str` | `''` | The tenant (first element of the identity tuple). |
| `consumer` | `str` | `''` | The calling integration's tag, recorded on the ledger row. |

| Output field | Type | Meaning |
| --- | --- | --- |
| `build_commit` | `str` | The git commit the serving image was built from; empty in a source run. |
| `schema_version` | `str` | The wire schema version, as the `X-Schema-Version` header names it. |
| `ops` | `list[OpCapability]` | Every registered operation, sorted by name, hidden ones included. |
| `consumer_field` | `str` | Every field of every request model that names the consumer — the tag stored on every ledger row. |

## `ops.health`

Run the deployment's self-checks (schema contracts, embedding stubs, ClickHouse parts, op mix, procedure plane, workers) and report each as ok, warn or fail.

`POST /v1/ops.health` · MCP `loom_ops_health` · role `org_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 \| None` | `None` | The namespace the op reads or writes. |

| Output field | Type | Meaning |
| --- | --- | --- |
| `checks` | `list[OpsHealthCheck]` | One entry per health check (schema contracts, embedding stubs, parts, op mix, workers, ...), each with its status and, when not `ok`, a suggested repair. |
| `worker_status` | `dict[str, dict[str, Any]]` | Per background worker in this process: last run time, duration, outcome, the last error's kind (`last_error_kind`), consecutive failures and total runs; empty before any worker has run. |
| `overall` | `Literal['ok', 'warn', 'fail']` | `fail` when any check failed, else `warn` when any warned, else `ok`. |

## `ops.projection_failures.list`

List recorded projection failures: derived rows (embeddings, graph edges, summaries) a write could not produce.

`POST /v1/ops.projection_failures.list` · MCP `loom_ops_projection_failures_list` · role `org_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 \| None` | `None` | The namespace the op reads or writes. |
| `projection` | `str` | `''` | Only failures of this projection (the derived table, such as `memory_chunks` or `entity_edges`); empty lists every projection. |
| `status` | `Literal['active', 'resolved', 'abandoned', '']` | `'active'` | `active` lists open failures, `resolved` repaired ones, `abandoned` those the repair gave up on (the reason is in `error_message`), empty all of them. |
| `limit` | `int` | `100` | At most this many failures, newest first; 1 to 1000. |

| Output field | Type | Meaning |
| --- | --- | --- |
| `rows` | `list[ProjectionFailureRow]` | The recorded failures matching the filters, newest first. |
| `total` | `int` | Number of rows returned (not the count beyond `limit`). |

## `ops.projection_failures.resolve`

Mark projection failures resolved by id without retrying them.

`POST /v1/ops.projection_failures.resolve` · MCP `loom_ops_projection_failures_resolve` · role `org_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). |
| `failure_ids` | `list[str]` | required | The failures to mark resolved without retrying them, 1 to 500 ids. |

| Output field | Type | Meaning |
| --- | --- | --- |
| `resolved` | `int` | Non-empty ids submitted for resolution; ids that match no active failure are counted. |

## `ops.projection_failures.retry`

Retry open projection failures for a namespace, optionally one projection kind.

`POST /v1/ops.projection_failures.retry` · MCP `loom_ops_projection_failures_retry` · role `org_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 \| None` | `None` | The namespace the op reads or writes. |
| `projection` | `str` | `''` | Only retry failures of this projection; empty retries every projection. |
| `limit` | `int` | `50` | At most this many active failures are retried, newest first; 1 to 1000. |

| Output field | Type | Meaning |
| --- | --- | --- |
| `results` | `list[ProjectionFailureRetryRow]` | One entry per failure attempted, with whether it was retried and resolved and why not. |
| `retried` | `int` | Failures whose projection has a retry path and was attempted. |
| `resolved` | `int` | Failures whose retry succeeded and which are now marked resolved. |
| `abandoned` | `int` | Failures the retry gave up on, now marked abandoned. |

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