Add File
Add a file to a knowledge base by upload or URL.
report.pdf to docs/ when it already exists returns 409.
Folders and files share the same namespace: you cannot upload a file whose name matches an existing folder in the same directory.Authorizations
Timbal API key. Obtain your API key from the Timbal platform settings. See Authentication for more information.
Body
Request body for adding a file to a knowledge base.
Provide either file (multipart bytes) or url (http/https). Exactly one is required.
Optional JSON metadata to attach to the file.
Optional subdirectory path within the knowledge base.
File bytes (multipart file field). Mutually exclusive with url.
x >= 0When set, overrides whether the file is parsed and embedded on upload.
Public http/https URL for the server to fetch and ingest. Mutually exclusive with file.
Response
File uploaded
Pipeline state for parsing + embedding.
One of pending (pipeline in flight), success (parse + embed both completed),
failed (latest attempt failed), or skipped (format unsupported, never parsed).
Unsupported files are stored as-is; the indicator lets clients flag them in listings
rather than rejecting the upload.
Deprecated (API): use signed_url when present. Legacy unsigned CDN URL
(content.timbal.ai during migration). Still populated server-side for old clients.
CloudFront signed URL on the new CDN for private content. Omitted when signing is unavailable or the object is public.