collections

collections.add_file

Add File to Collection

Effects: write

Add a file to a knowledge collection.

The file must be uploaded and indexed first (files_upload + files_ingest). If the file was previously removed, it is re-enabled.

Arguments

Argument	Type	Required	Description
collection_id	integer	yes	ID of the collection
file_id	integer	yes	ID of the file to add (from files_upload)

collections.assign_agent

Assign Collection to Agent

Effects: write

Assign a knowledge collection to an AI agent.

Once assigned, the agent's knowledge.query will automatically scope RAG search to files in its assigned collections.

Arguments

Argument	Type	Required	Description
agent_id	integer	yes	ID of the AI agent
collection_id	integer	yes	ID of the collection to assign

collections.create

Create Knowledge Collection

Effects: write

Create a named knowledge collection.

Collections group files for RAG search. After creating, add files with collections.add_file and assign to agents with collections.assign_agent.

Arguments

Argument	Type	Required	Description
description	string	no	Optional description of the collection
name	string	yes	Collection name (must be unique per user) (min 1.0; max 255.0)

collections.delete

Delete Knowledge Collection

Effects: delete

Delete a knowledge collection.

If the collection is assigned to agents, prompts, or channels, pass force=true to delete anyway. CASCADE removes all assignments automatically.

Arguments

Argument	Type	Required	Description
collection_id	integer	yes	ID of the collection to delete
force	boolean	no	Force delete even if collection is in use. OMIT for the safe default (refuse to delete in-use collections).

collections.list

List Knowledge Collections

Effects: read

List all knowledge collections in the workspace.

Collections are named groups of files used for RAG search. Auto-created collections (per-agent, per-prompt) are hidden by default.

Arguments

Argument	Type	Required	Description
include_inactive	boolean	no	Include inactive collections. OMIT to list only active collections (the default).

collections.list_files

List Files in Collection

Effects: read

List all files in a knowledge collection with their indexing status and chunk counts. Each returned file has a file_id (integer) that can be passed to messages.send as attachments=[file_id] to send the file to a contact, or to files.read to read its text content.

Arguments

Argument	Type	Required	Description
collection_id	integer	yes	ID of the collection

collections.remove_file

Remove File from Collection

Effects: write

Remove a file from a knowledge collection.

The file itself is not deleted — only the collection membership is removed.

Arguments

Argument	Type	Required	Description
collection_id	integer	yes	ID of the collection
file_id	integer	yes	ID of the file to remove

collections.unassign_agent

Unassign Collection from Agent

Effects: write

Remove a knowledge collection from an AI agent.

The collection and its files are not deleted — only the agent assignment is removed.

Arguments

Argument	Type	Required	Description
agent_id	integer	yes	ID of the AI agent
collection_id	integer	yes	ID of the collection to unassign