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

Add Website to Collection

Effects: write

Add a website to a knowledge collection. Its pages are indexed in the background (sitemap first, else links on the same host) and kept current.

Pass path_prefix (e.g. '/help') to index only one section. Check progress with collections.list_websites.

Arguments

Argument	Type	Required	Description
collection_id	integer	yes	ID of the knowledge collection
max_pages	integer	no	Maximum pages to index (1-500, default 100) (default 100)
path_prefix	string	no	Only index pages under this path, e.g. '/help'. OMIT for the whole site.
refresh_interval	string	no	How often to re-index automatically (default weekly) (one of off, daily, weekly; default weekly)
url	string	yes	Website address, e.g. 'https://example.com'

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

List Websites of Collection

Effects: read

List the websites of a knowledge collection with indexing status, pages indexed / found, last indexed time and last error.

Arguments

Argument	Type	Required	Description
collection_id	integer	yes	ID of the knowledge collection

collections.refresh_website

Refresh Website

Effects: write

Queue a website of a collection for re-indexing now. Unchanged pages are skipped.

Arguments

Argument	Type	Required	Description
collection_id	integer	yes	ID of the knowledge collection
source_id	integer	yes	ID of the website source (from collections.list_websites)

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

Remove Website from Collection

Effects: delete

Remove a website from a knowledge collection and DELETE every page file indexed from it. Cannot be undone.

Arguments

Argument	Type	Required	Description
collection_id	integer	yes	ID of the knowledge collection
source_id	integer	yes	ID of the website source (from collections.list_websites)

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