LIlighton
Files

Upload a file

Changed on

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, json, md, odp, odt, pdf, png, ppt, pptx, txt, xhtml, xls, xlsx, yaml, yml

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

Request

  • Base URL
    https://api.lighton.ai
  • URL
    https://api.lighton.ai/api/v3/files
  • Auth
    HTTP bearer

Request body application/x-www-form-urlencoded

filestring uri required

The file to upload (binary data)

filenamestring

Custom filename (defaults to uploaded filename if not provided)

titlestring

Custom title for the document. If not provided, defaults to filename without extension.

workspace_idinteger required

Workspace where the document will be stored.

parserstring

Deprecated — the platform always uses its default ingestion pipeline. This field is accepted but ignored. Will be removed in a future release.

tagsinteger[]

List of tag IDs to assign to the document on creation.

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

Changes

  • 63ecbc61b6a9Revision changes
    • breaking

      added subschema #2 to the response property oneOf list for the response status

    • breaking

      added subschema #2 to the response property oneOf list for the response status

    • breaking

      added subschema #2 to the response property oneOf list for the response status

    • info

      request property deprecated (media type: multipart/form-data)

    • info

      request property deprecated (media type: application/x-www-form-urlencoded)

    • info

      added the media type application/json for the response with the status

    • info

      added the media type application/json for the response with the status

    • info

      added the media type application/json for the response with the status

    • info

      added the media type application/json for the response with the status

    • info

      added the non-success response with the status

    • info

      added the non-success response with the status

    • info

      removed from the response property allOf list for the response status

    • info

      removed from the response property allOf list for the response status

    • info

      removed from the response property allOf list for the response status

    • info

      added the required property to the response with the status

    • info

      added the required property to the response with the status

    • info

      added the required property to the response with the status