curl --request POST \
--url https://api.lighton.ai/api/v3/files \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: multipart/form-data' \
--form 'file=(binary file data)' \
--form workspace_id=42{
"id": 12345,
"filename": "13144833.md",
"workspace": {
"id": 42,
"name": "My Workspace",
"workspace_type": "shared"
},
"title": "Patent 13144833",
"extension": "md",
"status": "embedded",
"status_vision": null,
"created_at": "2025-03-01T10:30:00Z",
"updated_at": "2025-03-01T10:30:00Z",
"total_pages": 3,
"tags": [],
"created_by": {
"id": 42,
"first_name": "Jane",
"last_name": "Doe",
"username": "jdoe"
},
"upload_session_uuid": null,
"external_metadata": {
"external_id": "hupd:13144833",
"doc_type": "",
"additional_metadata": {}
},
"message": "Document already exists (idempotent)"
}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, 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 filenameparser: Specify a custom ingestion pipeline instead of using the default
curl --request POST \
--url https://api.lighton.ai/api/v3/files \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: multipart/form-data' \
--form 'file=(binary file data)' \
--form workspace_id=42{
"id": 12345,
"filename": "13144833.md",
"workspace": {
"id": 42,
"name": "My Workspace",
"workspace_type": "shared"
},
"title": "Patent 13144833",
"extension": "md",
"status": "embedded",
"status_vision": null,
"created_at": "2025-03-01T10:30:00Z",
"updated_at": "2025-03-01T10:30:00Z",
"total_pages": 3,
"tags": [],
"created_by": {
"id": 42,
"first_name": "Jane",
"last_name": "Doe",
"username": "jdoe"
},
"upload_session_uuid": null,
"external_metadata": {
"external_id": "hupd:13144833",
"doc_type": "",
"additional_metadata": {}
},
"message": "Document already exists (idempotent)"
}Authorizations
Body
Request serializer for POST /api/v3/files endpoint.
Phase 1 Implementation - Core Parameters:
- file: The file to upload (required)
- name: Custom filename (optional, defaults to uploaded filename)
- title: Custom title for the document (optional)
- workspace_id: Workspace ID where the document will be stored (required)
- parser: Deprecated — ignored, the platform always uses its default pipeline
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.
pending- Pendingpending_conversion- Pending Conversionconverting- Convertingparsing- Parsingparsing_failed- Parsing Failedembedding- Embeddingembedding_failed- Embedding Failedembedded- Embeddedparsed- Parsedfail- Failupdating- Updating
pending, pending_conversion, converting, parsing, parsing_failed, embedding, embedding_failed, embedded, parsed, fail, updating