Manage document collections for retrieval

List Collections

Lists every collection in your company, newest first. Each item is enriched with documentCount and a rolled-up status the single-collection Get endpoint does not return.

Create Collection

Requires the OWNER or ADMIN role. Creates an empty document collection. Add documents to it with the manual-document endpoint, then attach it to a folder or agent with the map endpoint so something actually uses it.

Request body

Fields marked required are the ones the server rejects the request without. Anything conditional, where a field becomes required only alongside another, is described under Request rules above rather than marked here.

Get Collection

Fetches one collection by id, company-scoped. Does not include documentCount or status – those are only on the list response.

Parameters

Update Collection

Requires the OWNER or ADMIN role. Partial update: send only the fields to change. At least one of name or description is required.

Parameters

Request body

Fields marked required are the ones the server rejects the request without. Anything conditional, where a field becomes required only alongside another, is described under Request rules above rather than marked here.

Delete Collection

Requires the OWNER or ADMIN role. Deletes the collection, every document in it, their embeddings, and every mapping row pointing at it. An automation step that still names this collection is not touched – it starts failing to retrieve rather than being silently unlinked.

Parameters

List Documents

Lists every document in the collection, newest first. Each item’s full text is not included – fetch it separately from Get Document Text.

Parameters

Update Document

Requires the OWNER or ADMIN role. Renames the document’s title and/or description – the only fields this endpoint can change, at any status. A title change also propagates to that document’s stored chunk metadata so retrieval citations pick it up immediately.

Parameters

Request body

Fields marked required are the ones the server rejects the request without. Anything conditional, where a field becomes required only alongside another, is described under Request rules above rather than marked here.

Delete Document

Requires the OWNER or ADMIN role. Deletes the document and its embeddings. Looked up by documentId and your company alone – the kbId in the path is not cross-checked against the document’s own collection, so this succeeds even if docId actually belongs to a different one of your collections.

Parameters

Get Document Text

Fetches the extracted text of one document, company-scoped. A document that has not finished parsing yet is not an error: available is false, text is an empty string, and status shows the document’s current state.

Parameters

Add a Text Document

Requires the OWNER or ADMIN role. Adds a document with text you supply directly – the only way this endpoint set creates a document (uploading a file or crawling a website use endpoints not covered here). Kicks off embedding immediately; status starts at uploaded and moves toward ready on its own.

Parameters

Request body

Fields marked required are the ones the server rejects the request without. Anything conditional, where a field becomes required only alongside another, is described under Request rules above rather than marked here.

List Collection Owners

Everything this collection is attached to: folder and agent mappings from the map endpoint, plus every automation whose AI step names this collection directly (automations are never in the mapping table – their link is read live from the automation’s own steps, so it can’t go stale).

Parameters

Attach a Collection

Requires the OWNER or ADMIN role. Attaches this collection to a folder or agent, so retrieval actually uses it – a collection with no mapping is created but inert. Idempotent: mapping the same (collection, owner) pair again returns the existing row rather than erroring. ownerType cannot be automation here – an automation’s collection is set on its own AI step, not through this endpoint; see Get Collection Owners for how that link is surfaced instead.

Parameters

Request body

Fields marked required are the ones the server rejects the request without. Anything conditional, where a field becomes required only alongside another, is described under Request rules above rather than marked here.

Detach a Collection

Requires the OWNER or ADMIN role. Removes one mapping row. ownerType and ownerId are sent as query parameters on this DELETE, not a request body.

Parameters

List an Owner’s Collections

Reverse lookup: every collection mapped to a given folder or agent. Only covers real mapping rows, so an automation’s collection (which is never mapped, only referenced from its own AI step) will not appear here even though it shows up in that collection’s own Get Collection Owners response.

Parameters