Core concepts

Documents & knowledge base

Upload once per organization, embed into any workspace, and understand what deletion does.

Documents are the knowledge behind a workspace’s answers. They are uploaded at the organization level and then embedded into the workspaces that should be able to answer from them.

Org documents are shared across workspaces

A document lives in the organization’s storage, organized into folders. It is uploaded once and can then be embedded into any number of workspaces in that org.

Organization
├── folder: custom-documents   (the default catch-all)
│   └── handbook.pdf           ─┐ same document id
├── folder: policies           │  embedded into
│   └── refunds.pdf            │  many workspaces
└── ...                        ─┘
  • List folders: GET /v1/organizations/{orgId}/folders
  • Create a folder: POST /v1/organizations/{orgId}/folders
  • Upload a document: POST /v1/organizations/{orgId}/documents (multipart, field file; optional folder)

If you upload without naming a folder, the document lands in custom-documents. The target folder must already exist before you upload into it.

Supported single-document file types: pdf, docx, pptx, odt, odp, txt, md, rst, adoc, org, html, csv, epub.

A document’s title is taken from the uploaded filename, and there is no endpoint to rename it afterward. Give the file a clear, self-explanatory name before uploading — e.g. 2024-refund-policy.pdf rather than doc1.pdf. The filename is how you (and the assistant) recognize the document later, so it should make sense on its own.

A document’s id is stable and shared: the same id identifies the org document and every workspace embedding of it. You address the document by that one id everywhere — when embedding it, reading it, or deleting it.

Uploading is not embedding

Uploading a document makes it available in the org, but it is not queryable by any workspace until you embed it:

PUT /v1/workspaces/{workspaceId}/documents/{documentId}
  • The document must belong to the same organization as the workspace.
  • Embedding is idempotent — re-embedding a document that is already embedded in the workspace is a no-op and returns success.
  • Embedding builds the vector representation used for retrieval in that workspace.

List a workspace’s embedded documents with GET /v1/workspaces/{workspaceId}/documents.

What deletion does

There are two different “delete” operations, with very different blast radius:

Remove an embedded document from one workspace

DELETE /v1/workspaces/{workspaceId}/documents/{documentId}

This unembeds the document from that one workspace and deletes only that workspace’s vectors for it. The organization document itself is untouched, and any other workspace that has it embedded keeps working. Use this to stop one assistant from using a document.

Delete the organization document

DELETE /v1/organizations/{orgId}/documents/{documentId}

This permanently deletes the document from the org and automatically removes it from every workspace it was embedded into — the vectors are purged everywhere and the stored file is deleted. This cannot be undone.

Deleting the org document cascades to all its embeddings. Before deleting, read the document detail (GET /v1/organizations/{orgId}/documents/{documentId}) and check its embeddedWorkspaces — that list is the exact blast radius of the delete.

Deleting a folder (DELETE /v1/organizations/{orgId}/folders/{folderName}) deletes every document inside it, unembedding each one the same way.

Moving documents

  • Move a document to another folder: PATCH /v1/organizations/{orgId}/documents/{documentId}.

A document that is embedded in any workspace cannot be moved — the request is rejected with 409. Unembed it from every workspace first (DELETE /v1/workspaces/{workspaceId}/documents/{documentId} for each), move it, then re-embed. Check the document detail’s embeddedWorkspaces to see where it is currently embedded.

A document’s title cannot be changed after upload (it stays the original filename) — to “rename” one, upload the file again under the desired name and delete the old document.

Note there is no document download endpoint either: the original binary is discarded after text extraction, so only the extracted text (used for RAG) is retained.