collection operations

The exact fields each collection.* operation takes and returns.

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 its namespace and agent; see identities and namespaces. The operations index explains role, kind and the MCP all listing. Unknown input fields are served and named in ignored_args.

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