Upload File to Knowledge Base
Upload a file to an existing knowledge base. Supports PDF, TXT, DOCX, MD, CSV, and JSON files up to 50MB.
Adds one file to the knowledge base and indexes its text so agents can search it. A knowledge base holds at most 5 files, counting its text entry. Upload files one request at a time.
Requires the knowledge_base:create and knowledge_base:edit permissions.
Headers
x-workspace-idstringrequiredWorkspace identifier for the API.
Path Parameters
idstringrequiredThe unique identifier of the knowledge base to upload the file to.
Request Body
The request body should be sent as multipart/form-data.
uploadedFilefilerequiredThe file to upload. Supported formats: PDF, TXT, DOCX, MD, CSV, JSON (checked by MIME type, or by file extension when the MIME type is generic). Maximum file size: 50MB. One file per request.
duplicateStrategystringWhat to do when the knowledge base already has a file with the same name:
replace: swap the existing file for the new one. This doesn't count toward the 5-file limit.keep-both: keep both files.
Leave it out and a duplicate name is refused with 409 KB_DUPLICATE_FILENAME, so you can decide.
Response
201 with the new file entry.
filenamestringName of the uploaded file.
keystringStorage key of the file. Unique per upload.
urlstringStorage location of the file. Not a public link.
mimetypestringMIME type of the file, as sent.
sizenumberSize of the file in bytes.
uploadedAtstringWhen the file was uploaded.
indexedbooleanWhether text was extracted and indexed for search. false means the file is stored but agents can't search it.
chunksnumberNumber of indexed chunks. 0 when indexed is false.
indexSkippedReasonstring | nullWhy the file wasn't indexed, for example no-extractable-text (such as a scanned PDF with no text layer). null when it was indexed.
Errors
| Status | Body | When |
|---|---|---|
400 | {"message": "Workspace ID header is required"} | No x-workspace-id |
400 | {"message": "No file uploaded"} | No uploadedFile part |
400 | {"message", "code": "KB_SINGLE_FILE_PER_REQUEST"} | More than one file in the request |
400 | {"message", "code": "KB_UNSUPPORTED_FILE_TYPE"} | The file isn't one of the supported formats |
409 | {"message", "code": "KB_DUPLICATE_FILENAME", "details": {"filename"}} | A file with this name already exists and no duplicateStrategy was sent |
409 | {"message", "code": "KB_FILE_LIMIT_REACHED", "details": {"limit", "current"}} | The knowledge base already holds 5 files |
500 | {"message": "..."} | Anything else. The uploaded file is not kept |
curl -X POST https://api.trillet.ai/v1/api/knowledgebase/a4a4a4a4a4a4a4a4a4a4a4a4/files \
-H "x-api-key: YOUR_API_KEY" \
-H "x-workspace-id: YOUR_WORKSPACE_ID" \
-F "uploadedFile=@product-guide.pdf" \
-F "duplicateStrategy=replace"{
"filename": "product-guide.pdf",
"key": "workspaces/d1d1d1d1d1d1d1d1d1d1d1d1/knowledge-bases/a4a4a4a4a4a4a4a4a4a4a4a4/1761735600000-product-guide.pdf",
"url": "https://example-bucket.s3.amazonaws.com/workspaces/d1d1d1d1d1d1d1d1d1d1d1d1/knowledge-bases/a4a4a4a4a4a4a4a4a4a4a4a4/1761735600000-product-guide.pdf",
"mimetype": "application/pdf",
"size": 1048576,
"uploadedAt": "2026-10-29T10:00:00.000Z",
"indexed": true,
"chunks": 42,
"indexSkippedReason": null
}Last updated on