Agents

Add documents to the library

Upload a file to the workspace knowledge library and follow it through indexing until the agent can use it.

Uploading a document puts it in the workspace library and sends it for indexing. Once it reaches Ready, any agent that has selected it can quote from it.

What you need

  • A workspace you are a member of. Any member can add, rename and delete sources.
  • A file in one of the ten supported formats, under the size limits below.
  • Enough remaining storage on your plan.

Steps

Step 1: Open the library

Go to Knowledge base in the left navigation to add the file to the workspace library, or open an agent and go to its Knowledge tab to add it and attach it to that agent in one pass.

Step 2: Start the add flow

Click Add in the library, or Add New on an agent's Knowledge tab, then choose Upload File. The dialog opens on that tab.

Step 3: Choose the file

Drop the file on Drop a file here or click to browse, or click to pick it. The picker accepts the supported extensions and their common alternative spellings, so a .jpeg or a .htm is still selectable.

Step 4: Choose where it lands

Under Location, leave Library root to keep the source loose, or pick a folder. A loose source can be attached to an agent on its own. A source inside a folder is only reached by selecting that folder.

Step 5: Add it

Click Add. The file uploads from your browser, so keep the tab open until the row appears in the list.

Get it right

Only the text that can be extracted from a file is searchable, so the format you upload decides whether the agent can answer from it. Check the Chunks count after a source turns Ready: a handful of chunks on a long document means almost nothing was extracted.

Recommended

  • A PDF exported from the original document, with selectable text.
  • A .docx or .md of the policy itself.

Less effective

  • A scanned PDF or a photo of a printed page.
  • A slide deck whose words live inside images.

Worked example

You upload returns-policy.pdf, 1.2 MB, into a folder called Returns. The row appears at Uploading, moves to Pending, then Indexing, and about a minute later reads Ready with 34 in the Chunks column and a Document indexed notification.

On the returns agent you select the Returns folder, turn on Enable retrieval, and ask it what the return window is. Thirty-four chunks on a two-page policy is a healthy count; a count of 1 would have told you the PDF was a scan.

What happens next

The source appears in the list immediately and moves through a fixed ladder. The row updates on its own, with no refresh.

Status Portal label What it means
uploading Uploading The row exists and your browser is still sending the file.
uploaded Pending The file has arrived and is queued for indexing.
processing Indexing The text is being extracted and indexed.
ready Ready Indexing finished. The chunk count is filled in and agents can use the source.
failed Failed Indexing did not finish. The row carries the reason.

When indexing finishes you also get a notification: Document indexed on success, Document failed to index on failure, each naming the file.

Steps have no fixed duration; a large document takes longer than a short one. Two timeouts bound the wait:

  • A source left at Uploading for more than 10 minutes is moved on if the file did arrive, and removed with its storage returned if it did not.
  • A source left at Indexing for more than 60 minutes fails with Indexing timed out. Try again.

Limits

Limit Value Applies to
Extensions pdf, docx, pptx, xlsx, html, md, png, jpg, tiff, bmp Every upload
Extension aliases jpeg to jpg, tif to tiff, htm to html, markdown to md Filename matching
File size in the portal 20 MB per file The upload dialog
File size at the API A cap of its own; the refusal names the exact figure The upload request
Filename length 255 characters The upload request
Display name length 200 characters The upload request and renaming
Workspace storage Your plan's storage allowance All files and pasted text together

The portal refuses anything over 20 MB before it uploads. The API enforces a cap of its own and names the exact number of bytes when it refuses.

Troubleshooting

Unsupported type .xyz. Allowed: pdf, docx, pptx, xlsx, html, md, png, jpg, tiff, bmp.

The extension is not one of the ten, and is not one of the four aliases. Convert the file. A .doc, a .txt or a .csv is not accepted today; save it as .docx, .md or .xlsx.

The portal catches this before the upload starts. A request that reaches the API with an unsupported name is answered with Unsupported file type. Allowed: pdf, docx, pptx, xlsx, html, md, png, jpg, tiff, bmp.

MIME type ... does not match extension ...

The file's extension and the content type your browser reported disagree. This is almost always a renamed file: a PDF saved as report.docx, for example. Rename it back to its real extension, or re-export it in the format the name claims.

An unrecognized or empty content type is not an error. Markdown files often report nothing at all, and the extension is used.

File is larger than 20 MB.

The portal's own cap, checked before anything is uploaded. Split the document, or remove embedded images and re-export it.

File exceeds size limit (N bytes)

The API's cap. The number in the message is the exact limit in bytes.

Storage limit exceeded for this workspace. Delete files or upgrade your plan.

Your plan's storage allowance is full. Delete sources you no longer need, which frees their bytes, or move to a larger plan.

This file is larger than your plan's remaining storage. Delete files or upgrade your plan.

The same condition, caught in the browser before the upload starts.

File not found in storage. Retry the upload.

The upload was interrupted and the file never arrived. Delete the row and upload the file again.

Indexing timed out. Try again.

The source sat at Indexing for over an hour. Delete it and upload it again.

The row says Failed

Open the row to read the reason. Scanned PDFs with no text layer and password-protected files are the common causes. A file source has no re-index action, so fix the document, delete the row and upload it again.

FAQ

Can I replace a file without losing the agents that use it?

No. There is no in-place replace for a file source. Upload the new version, attach it, then delete the old one.

Does uploading from an agent's Knowledge tab keep the file private to that agent?

No. Every source goes into the workspace library and is visible to the whole workspace. Adding from an agent also selects it for that agent.

Can I download a file I uploaded?

Yes. Use Download in the row menu. It opens a short-lived link to the stored original.

What does the Chunks column mean?

The number of passages the document was split into. A ready file with a very low chunk count had very little extractable text.

Are images really supported?

png, jpg, tiff and bmp are accepted and indexed. How much text comes out of one varies, so check the chunk count after the source turns Ready before relying on an image.