Knowledge
Libraries, collections, and documents that make up the knowledge base.
List collections
With `applicationId` the list contains the collections attached to that application, otherwise every collection of the caller’s company that the caller can see. `libraryId` narrows either list to one library. Only ACTIVE collections are returned.
Create a collection
Body: `{ name, description?, icon?, isPrivate?, libraryId }`. Validation failures answer `400 { error: 'Validation failed', details }`.
Get a collection
Returns one ACTIVE collection in the same item shape as the `GET /api/collections/` list. Access follows the shared collection visibility rules (owner, member, application member, or public).
Update a collection
Updates any subset of `name`, `description`, `icon`, and `isPrivate`; `libraryId` moves the collection to another library. Moving into a private library also makes the collection (and its documents) private.
Archive a collection
Soft delete: archives the collection together with its documents and repositories. Archived collections disappear from every listing and their knowledge stops being retrievable.
List libraries
With `applicationId` the list contains the libraries of the collections attached to that application, otherwise every library of the caller’s company that the caller can see. The company-wide list is served from cache.
Create a library
Body: `{ name, isPrivate? }`. Validation failures answer `400 { error: 'Validation failed', details }`.
Get a document
Returns one document with its user, collection, and summarized knowledge entries. Documents outside the caller’s visibility answer 404.
Rename a document
Updates the user-facing filename and/or title of a document. The stored file extension is preserved, and an empty `title` clears the user-defined title. Requires write access to the document’s collection.
Delete a document
Soft delete: the document is archived and its knowledge entries stop being retrievable. Requires write access to the document’s collection.
Get the processing status of a document
Intended for polling after an upload: the status moves from `QUEUED` through `PROCESSING` to `COMPLETED` or `FAILED` once ingestion finishes. The response is never cached.
List assistant threads of a document
`limit` is clamped to 1-100 (default 50) and `page` is 1-based (values below 1 are treated as 1).
Copy a document into another collection
Takes the source document id as the `id` path parameter and a JSON body `{ collectionId }` (destination collection). Failure responses other than the invalid-id 400 are plain-text bodies.
Generate embeddings for a collection in the background
Optional body: `{ generateText?, generateMultimodal?, force?, batchSize? }`. Returns immediately with the number of entries queued; generation continues in the background.
List documents in a collection
One page of the collection documents, most recently updated first. When `search` is set, the page is ranked by semantic similarity to the query instead. Requires read access to the collection.
Upload documents to a collection
Multipart upload of one or more files into a collection. Large files can use the resumable chunked protocol driven by the `x-resume-token`, `x-resume-from-byte` and `x-total-file-size` request headers (see `src/shared/chunked-upload.ts`); plain multipart posts of the `files` field work without any of them. Requires write permission on the collection.
Create a one-time document upload URL
The two-step upload for callers that cannot send multipart/form-data (MCP hosts, plain scripts): this operation returns a short-lived, single-use URL, and sending the raw file bytes to it with PUT ingests the file into the collection exactly like a regular upload. The URL inherits the permissions of whoever created it. For files up to ~30MB; larger files should use the multipart endpoint with the resumable chunked protocol.
Send the file bytes for a one-time upload URL
Second step of the two-step upload: PUT the raw file bytes to the URL returned by `createDocumentUploadUrl`. The URL is single-use and expires; no authentication header is required because the URL itself is the credential.
Download a document
Streams the document bytes. `size` (e.g. `SMALL`, `MEDIUM`, `LARGE`, `WHATSAPP`) serves a resized variant for images; `pdfPreviewType=image` serves a PDF page rendered as an image. The response content type follows the stored file.