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)"
}

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

files

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

Authorization

string

header

required

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: Pipeline to use for ingestion processing (optional)

Changes from V2:

Removed: collection_type (workspace_id is now the source of truth)
Removed: collection (derived automatically from workspace_id)
Simplified: workspace_id is now required and is the single source of truth

Phase 2 (Deferred):

chunk_size, chunk_overlap
OCR configuration parameters
These may be reorganized into nested configuration objects

file

string<uri>

required

The file to upload (binary data)

workspace_id

integer

required

Workspace where the document will be stored.

filename

string

Custom filename (defaults to uploaded filename if not provided)

Maximum string length: 255

title

string

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

Maximum string length: 255

parser

string

Ingestion pipeline to use. Only 'v2.2.1' is accepted. If omitted, the platform default is used.

Maximum string length: 255

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.

integer

required

read-only

filename

string

required

read-only

Filename of the document

workspace

object | null

required

Workspace the document belongs to

Show child attributes

summaries

object[]

required

read-only

Document summaries (all languages)

Show child attributes

extension

string

required

File extension of the document

created_at

string<date-time>

required

Creation date of the resource

updated_at

string<date-time>

required

read-only

total_pages

integer

required

read-only

Total number of pages