---
title: collection operations
---

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

## `collection.create`

Create a collection: a namespace read and written only through grants.

`POST /v1/collection.create` · MCP `loom_collection_create` · role `viewer` · 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` | `''` | The collection's name, also its namespace ('col-' then lowercase letters, digits and '-'), ignored with `derive_name`. |
| `title` | `str` | `''` | What the collection is called on screen (at most 200 characters, no control or invisible ones; titles repeat across the org); '' for none. |
| `derive_name` | `bool` | `False` | Derive the name from `title`, not `namespace`; a title used under the parent (top level: the caller's own) answers that one. |
| `parent` | `str` | `''` | The collection it sits in and inherits grants from; '' for a top-level one. |
| `description` | `str` | `''` | What the collection holds, shown beside its name (at most 2000 characters); '' for none. |

| Output field | Type | Meaning |
| --- | --- | --- |
| `namespace` | `str` | The namespace the op reads or writes. |
| `parent` | `str` | The collection it sits in; '' for a top-level one. |
| `created` | `bool` | False when the collection already existed: the caller's own by that name, or the one the title already names there. |
| `title` | `str` | The collection's title; '' for none. |

## `collection.delete`

Delete a collection with what it holds: a purging erasure of the namespace (documents, chunks, originals, memory leave the disk), then it leaves the directory and the tree, and its name is never used…

`POST /v1/collection.delete` · MCP `loom_collection_delete` · 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. |

| Output field | Type | Meaning |
| --- | --- | --- |
| `namespace` | `str` | The namespace the op reads or writes. |
| `deleted` | `bool` | False when it was already deleted |
| `erasure_id` | `str` | The erasure of what the collection held; `erasure.status` follows it. |
| `erasure_status` | `str` | That erasure's outcome: `completed`, or `failed` while the recovery worker retries it. |

## `collection.list`

List the collections the caller can read, by name.

`POST /v1/collection.list` · MCP `loom_collection_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). |
| `limit` | `int` | `500` | Collections per page. |
| `include_document_counts` | `bool` | `False` | Include the live document count directly in each collection; default false. |
| `cursor` | `str \| None` | `None` | The `next_cursor` of the previous page; none for the first. |

| Output field | Type | Meaning |
| --- | --- | --- |
| `collections` | `list[_CollectionEntry]` | The collections the caller can read on this page, by name, with the caller's role and the collection's title and description. |
| `next_cursor` | `str \| None` | Pass as `cursor` for the next page; none on the last. |

## `collection.move`

Put a collection under another one, or detach it.

`POST /v1/collection.move` · MCP `loom_collection_move` · 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. |
| `parent` | `str` | `''` | The new parent collection; '' detaches it, keeping only its own grants. |

| Output field | Type | Meaning |
| --- | --- | --- |
| `namespace` | `str` | The namespace the op reads or writes. |
| `parent` | `str` | The collection it now sits in; '' once detached. |
| `moved` | `bool` | False when it already sat there |

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