Sign in

v1

latestOpenAPI 3.1.02026-07-263580186.3 KB
Files

Upload a file

Upload a file to a workspace.

Files are added to an upload session and queued for asynchronous processing. To track progress, retrieve the file details using the GET endpoints to check the current status.

Idempotent upload: When external_metadata.external_id is provided and a manually-uploaded document with the same external ID already exists in the target workspace, the existing document is returned with 200 OK instead of creating a duplicate. This makes bulk re-runs safe without requiring a pre-check. Datasource-imported documents are not affected.

Accepted file formats: csv, doc, docx, htm, html, jpeg, jpg, md, odp, odt, pdf, png, ppt, pptx, txt, xhtml, xls, xlsx

Customization Options:

  • title: Customize the document title (defaults to filename without extension)
  • filename: Override the uploaded filename
  • parser: Specify a custom ingestion pipeline instead of using the default
post/api/v3/files

Response

Document already exists (idempotent). Returned when external_metadata.external_id matches a manually-uploaded document in the same workspace. The existing document is returned without creating a duplicate.

idinteger required
filenamestring required

Filename of the document

titlestring nullable
extensionstring required

File extension of the document

status'pending' | 'pending_conversion' | 'converting' | 'parsing' | 'parsing_failed' | 'embedding' | 'embedding_failed' | 'embedded' | 'parsed' | 'fail' | 'updating'
  • pending - Pending
  • pending_conversion - Pending Conversion
  • converting - Converting
  • parsing - Parsing
  • parsing_failed - Parsing Failed
  • embedding - Embedding
  • embedding_failed - Embedding Failed
  • embedded - Embedded
  • parsed - Parsed
  • fail - Fail
  • updating - Updating
status_vision'pending' | 'processing' | 'embedded' | 'fail' | '-'
  • pending - Pending
  • processing - Processing
  • embedded - Embedded
  • fail - Fail
  • - - Not available
created_atstring date-time required

Creation date of the resource

updated_atstring date-time required
total_pagesinteger required

Total number of pages

upload_session_uuidstring uuid nullable required

Upload session UUID associated with this document

messagestring required

Status message about the file upload