curl --request POST \
--url https://paradigm.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, 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 filenameparser: Specify a custom ingestion pipeline instead of using the default
curl --request POST \
--url https://paradigm.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
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
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
The file to upload (binary data)
Workspace where the document will be stored.
Custom filename (defaults to uploaded filename if not provided)
255Custom title for the document. If not provided, defaults to filename without extension.
255Deprecated — the platform always uses its default ingestion pipeline. This field is accepted but ignored. Will be removed in a future release.
255List of tag IDs to assign to the document on creation.
External source metadata for documents ingested from third-party systems. Provide as a JSON object with external_id (required), doc_type (optional), and additional_metadata (optional JSON object).
Show child attributes
Show child attributes
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.
Filename of the document
Workspace the document belongs to
Show child attributes
Show child attributes
Document summaries (all languages)
Show child attributes
Show child attributes
File extension of the document
Creation date of the resource
Total number of pages
List of tags associated with the document
Show child attributes
Show child attributes
User who created the file. Null when the file was created by the system.
Show child attributes
Show child attributes
Upload session UUID associated with this document
External document metadata
Show child attributes
Show child attributes
Status message about the file upload
Thumbnail preview of the document (256x256 WebP).
Show child attributes
Show child attributes
255pending- 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 pending- Pendingprocessing- Processingembedded- Embeddedfail- Fail-- Not available
pending, processing, embedded, fail, -