API ReferenceDocument Catalog

Upload File

Upload a file (PDF, Word, Excel, CSV, PowerPoint) to Credal. Unlike uploadDocumentContents which requires pre-parsed text, this endpoint accepts actual file uploads and automatically parses them using Credal’s parsing service.

Authentication

AuthorizationBearer

Bearer authentication of the form Bearer <token>, where token is your auth token.

Request

This endpoint expects a multipart form containing a file.
filefileRequired

The file to upload. Supported formats: PDF (.pdf), Word (.docx), Excel (.xlsx, .xls), PowerPoint (.pptx, .ppt), CSV (.csv), and text files.

documentNamestringOptional
The name of the document you want to upload. If not provided, the original filename will be used.
uploadAsUserEmailstringRequired

[Legacy] The user on behalf of whom the document should be uploaded. In most cases, this can simply be the email of the developer making the API call. This field will be removed in the future in favor of purely specifying permissions via allowedUsersEmailAddresses.

documentExternalIdstringRequired
The external ID of the document. This is typically the ID as it exists in its original external system. Uploads to the same external ID will update the document in Credal.
allowedUsersEmailAddressesstringOptional
Users allowed to access the document. Can be provided as a JSON array string (e.g., ["user1@example.com","user2@example.com"]) or comma-separated list (e.g., "user1@example.com,user2@example.com"). Unlike Credal's out of the box connectors which reconcile various permissions models from 3rd party software, for custom uploads the caller is responsible for specifying who can access the document and currently flattening groups if applicable. Documents can also be marked as internal public.
documentExternalUrlstringOptional
The external URL of the document you want to upload. If provided Credal will link to this URL.
customMetadatastringOptional

Optional JSON string representing any custom metadata for this document (e.g., ’{“key1”:“value1”,“key2”:“value2”}’).

collectionIdstringOptional

If specified, the document will also be added to the provided document collection. This operation is eventually consistent, meaning the document does not immediately start appearing in searches of that collection due to an asynchronous embedding process. To achieve strong consistency use the awaitVectorStoreSync parameter.

forceUpdatestringOptional

If set to “true”, document contents will be re-uploaded and re-embedded even if the document already exists in Credal.

internalPublicstringOptional
If set to "true", document will be accessible to everyone within the organization of the uploader.
sourceSystemUpdatedstringOptional

ISO 8601 date string indicating when the document was last updated in the source system (e.g., “2025-11-03T21:15:00Z”).

awaitVectorStoreSyncstringOptional
Document uploads are eventually consistent by default. If set to "true" the API will wait for the vector store to be updated before returning. This is useful if you want to ensure that the document is immediately searchable after this call returns.

Response

This endpoint returns an object.
documentIdUUID