Trillet AI logo

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.

POSThttps://api.trillet.ai/v1/api/knowledgebase/{id}/files

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-idstringrequired

Workspace identifier for the API.

Path Parameters

idstringrequired

The unique identifier of the knowledge base to upload the file to.

Request Body

The request body should be sent as multipart/form-data.

uploadedFilefilerequired

The 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.

duplicateStrategystring

What 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.

filenamestring

Name of the uploaded file.

keystring

Storage key of the file. Unique per upload.

urlstring

Storage location of the file. Not a public link.

mimetypestring

MIME type of the file, as sent.

sizenumber

Size of the file in bytes.

uploadedAtstring

When the file was uploaded.

indexedboolean

Whether text was extracted and indexed for search. false means the file is stored but agents can't search it.

chunksnumber

Number of indexed chunks. 0 when indexed is false.

indexSkippedReasonstring | null

Why 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

StatusBodyWhen
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