> ## Documentation Index > Fetch the complete documentation index at: https://developers.lighton.ai/llms.txt > Use this file to discover all available pages before exploring further. # 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 ## OpenAPI ````yaml /api-reference/api-console.yaml post /api/v3/files openapi: 3.1.0 info: title: LightOn API version: 3.15.0 (v1) description: >- LightOn gives you an API to search, parse, and ingest documents at scale. Build knowledge-retrieval pipelines without managing vector databases or OCR models. servers: - url: https://api.lighton.ai security: [] tags: - name: Ask description: >- Retrieval-augmented generation: search your indexed corpus and generate an LLM answer grounded in the retrieved passages. Supports streaming (SSE) and synchronous modes. - name: Search description: >- Hybrid vector + text retrieval over your indexed corpus. Returns ranked passages with provenance (file, page range, workspace). Optional reranking and vision mode. - name: Files description: Upload, list, fetch, and delete documents indexed in your workspaces. - name: Facets description: >- Organise documents with hierarchical content types and custom attributes per file. Start from starter templates or build your own classification schema from scratch. - name: Tags description: >- Manage flat, company-wide labels used to scope search and group content across workspaces. - name: Workspaces description: >- Create and manage workspaces — the access-controlled containers your documents live in. - name: Parse description: >- Convert documents into structured Markdown — PDFs, images, Office files, and HTML. Synchronous endpoint capped at 20 MB / 15 pages. - name: Extract description: >- Pull typed fields out of documents using a JSON Schema you provide. Sync mode for small documents (≤20 MB / 15 pages); async mode for larger jobs (≤100 MB / 1000 pages) with polling on a job ID. - name: API Keys description: >- Provision and revoke API keys used to authenticate against the Console API. - name: Budget description: >- Manage your organization's monthly spend budget and alert thresholds. Set a hard cap that blocks API requests when reached, and configure email notifications at custom spend percentages. paths: /api/v3/files: post: tags: - Files summary: Upload a file description: >+ 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 operationId: api_v3_files_create requestBody: content: multipart/form-data: schema: $ref: '#/components/schemas/FileCreateRequestSerializerV3' examples: BasicFileUpload: value: file: (binary file data) workspace_id: 42 summary: Basic file upload description: Upload a PDF file with only required fields FileUploadWithCustomMetadataAndTags: value: file: (binary file data) workspace_id: 42 filename: Q4_Report_2025.pdf title: Q4 Financial Report tags: - 1 - 2 summary: File upload with custom metadata and tags description: >- Upload a file with custom filename, title, and manual tag assignment. Tags can be sent as a JSON array string (e.g., '[1,2]') or as multiple form fields with the same name. IdempotentUploadWithExternalId: value: file: (binary file data) workspace_id: 42 external_metadata: external_id: hupd:13144833 summary: Idempotent upload with external_id description: >- Upload with `external_id` for idempotent re-runs. If a manually-uploaded document with the same `external_id` already exists in the workspace, the server returns 200 OK with the existing document instead of creating a duplicate. Datasource-imported documents are not affected — idempotency is scoped to manual uploads only. FileUploadWithExternalMetadata: value: file: (binary file data) workspace_id: 42 external_metadata: external_id: SRV-456789 doc_type: incident additional_metadata: external_url: https://servicenow.example.com/incident/SRV-456789 external_full_path: ServiceNow > Incidents > SRV-456789 created_at: '2024-01-10T08:00:00Z' modified_at: '2024-01-12T16:45:00Z' summary: File upload with external metadata description: >- Upload a file that originates from an external system (e.g. ServiceNow, SharePoint). `external_metadata` must be sent as a JSON string when using multipart/form-data. `external_id` is required; `doc_type` and `additional_metadata` are optional. application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/FileCreateRequestSerializerV3' examples: BasicFileUpload: value: file: (binary file data) workspace_id: 42 summary: Basic file upload description: Upload a PDF file with only required fields FileUploadWithCustomMetadataAndTags: value: file: (binary file data) workspace_id: 42 filename: Q4_Report_2025.pdf title: Q4 Financial Report tags: - 1 - 2 summary: File upload with custom metadata and tags description: >- Upload a file with custom filename, title, and manual tag assignment. Tags can be sent as a JSON array string (e.g., '[1,2]') or as multiple form fields with the same name. IdempotentUploadWithExternalId: value: file: (binary file data) workspace_id: 42 external_metadata: external_id: hupd:13144833 summary: Idempotent upload with external_id description: >- Upload with `external_id` for idempotent re-runs. If a manually-uploaded document with the same `external_id` already exists in the workspace, the server returns 200 OK with the existing document instead of creating a duplicate. Datasource-imported documents are not affected — idempotency is scoped to manual uploads only. FileUploadWithExternalMetadata: value: file: (binary file data) workspace_id: 42 external_metadata: external_id: SRV-456789 doc_type: incident additional_metadata: external_url: https://servicenow.example.com/incident/SRV-456789 external_full_path: ServiceNow > Incidents > SRV-456789 created_at: '2024-01-10T08:00:00Z' modified_at: '2024-01-12T16:45:00Z' summary: File upload with external metadata description: >- Upload a file that originates from an external system (e.g. ServiceNow, SharePoint). `external_metadata` must be sent as a JSON string when using multipart/form-data. `external_id` is required; `doc_type` and `additional_metadata` are optional. required: true responses: '200': content: application/json: schema: $ref: '#/components/schemas/FileCreateResponseSerializerV3' examples: Idempotent—DocumentAlreadyExists: value: 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) summary: Idempotent — document already exists description: >- The document with this external_id was already uploaded to this workspace. No new document is created. The response body is identical to a normal upload response. description: >- 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. '201': content: application/json: schema: $ref: '#/components/schemas/FileCreateResponseSerializerV3' examples: FileUploadedSuccessfully: value: id: 12345 filename: document.pdf workspace: id: 42 name: My Workspace workspace_type: shared summaries: [] title: document extension: pdf status: pending status_vision: null created_at: '2025-03-01T10:30:00Z' updated_at: '2025-03-01T10:30:00Z' total_pages: 0 tags: [] created_by: id: 42 first_name: Jane last_name: Doe username: jdoe upload_session_uuid: 550e8400-e29b-41d4-a716-446655440000 external_metadata: null message: File queued for processing summary: File uploaded successfully FileUploadedWithTags: value: id: 12346 filename: compliance_doc.pdf workspace: id: 42 name: My Workspace workspace_type: shared summaries: [] title: Compliance Document extension: pdf status: pending status_vision: null created_at: '2025-03-01T10:35:00Z' updated_at: '2025-03-01T10:35:00Z' total_pages: 0 tags: - id: 1 name: Compliance auto_assigned: false - id: 2 name: Legal auto_assigned: false created_by: id: 42 first_name: Jane last_name: Doe username: jdoe upload_session_uuid: 550e8400-e29b-41d4-a716-446655440000 external_metadata: null message: File queued for processing summary: File uploaded with tags FileUploadedWithExternalMetadata: value: id: 12348 filename: SRV-456789.pdf workspace: id: 42 name: My Workspace workspace_type: shared summaries: [] title: SRV-456789 extension: pdf status: pending status_vision: null created_at: '2025-03-01T10:40:00Z' updated_at: '2025-03-01T10:40:00Z' total_pages: 0 tags: [] created_by: id: 42 first_name: Jane last_name: Doe username: jdoe upload_session_uuid: 550e8400-e29b-41d4-a716-446655440000 external_metadata: external_id: SRV-456789 doc_type: incident additional_metadata: external_url: https://servicenow.example.com/incident/SRV-456789 external_full_path: ServiceNow > Incidents > SRV-456789 message: File queued for processing summary: File uploaded with external metadata description: >- Upload response when external_metadata was provided. The record is created synchronously and returned immediately. description: File queued for processing successfully '207': content: application/json: schema: $ref: '#/components/schemas/FileCreateResponseSerializerV3' examples: FileUploadedWithTagError: value: id: 12347 filename: document.pdf workspace: id: 42 name: My Workspace workspace_type: shared summaries: [] title: document extension: pdf status: pending status_vision: null created_at: '2025-03-01T10:40:00Z' updated_at: '2025-03-01T10:40:00Z' total_pages: 0 tags: [] created_by: id: 42 first_name: Jane last_name: Doe username: jdoe upload_session_uuid: 550e8400-e29b-41d4-a716-446655440000 external_metadata: null message: >- Document uploaded successfully, but tag assignment failed: Invalid or unauthorized tag IDs: 999 summary: File uploaded with tag error description: Document uploaded successfully but tags failed to assign description: Document uploaded but tag assignment failed (partial success) '400': content: application/json: schema: $ref: '#/components/schemas/APIV3ErrorResponse' examples: StorageLimitReached: value: id: null code: 400 error: STORAGE_LIMIT_REACHED detail: >- The custom workspace storage limit for your company is 500 MB and you are currently using 487.3 MB. Delete stale documents or ask your company admin to request an increase of your storage quota. doc_url: https://developers.lighton.ai/errors#STORAGE_LIMIT_REACHED summary: Storage limit reached UploadsDisabled: value: id: null code: 400 error: UPLOADS_DISABLED detail: >- Uploads are disabled for the custom workspace. The storage limit is set to 0 MB. Ask your company admin to request an increase of your storage quota. doc_url: https://developers.lighton.ai/errors#UPLOADS_DISABLED summary: Uploads disabled description: >- Domain error — the upload exceeds the workspace storage limit or uploads are disabled. The domain code is carried in `error` and the limit/usage in `detail`. '401': content: application/json: schema: $ref: '#/components/schemas/APIV3ErrorResponse' examples: Unauthorized: value: id: null code: 401 error: unauthorized detail: >- Authentication credentials were not provided or are invalid. doc_url: https://developers.lighton.ai/errors#unauthorized description: Authentication credentials were not provided or are invalid '403': content: application/json: schema: $ref: '#/components/schemas/APIV3ErrorResponse' examples: Forbidden: value: id: null code: 403 error: insufficient_permissions detail: You do not have permission to perform this action. doc_url: >- https://developers.lighton.ai/errors#insufficient_permissions description: Insufficient permissions '422': content: application/json: schema: $ref: '#/components/schemas/APIV3ValidationErrorResponse' examples: MissingRequiredField: value: id: null code: 422 error: validation_error detail: One or more fields failed validation. doc_url: https://developers.lighton.ai/errors#validation_error fields: workspace_id: - error: required detail: This field is required. summary: Missing required field InvalidFileType: value: id: null code: 422 error: validation_error detail: One or more fields failed validation. doc_url: https://developers.lighton.ai/errors#validation_error fields: file: - error: invalid detail: File extension not supported. summary: Invalid file type SyncedWorkspace: value: id: null code: 422 error: validation_error detail: One or more fields failed validation. doc_url: https://developers.lighton.ai/errors#validation_error fields: non_field_errors: - error: invalid detail: >- Cannot manually upload documents to a workspace configured for synced documents. summary: Synced workspace description: >- Validation error — missing/invalid fields or a synced workspace. Per-field errors in `fields`. '429': content: application/json: schema: $ref: '#/components/schemas/APIV3ErrorResponse' examples: TooManyRequests: value: id: null code: 429 error: too_many_requests detail: Too many requests. Please try again later. doc_url: https://developers.lighton.ai/errors#too_many_requests summary: Too Many Requests description: Too many requests '503': description: >- API is under maintenance. Check `GET /api/v3/system/status` for active periods and retry. content: application/json: schema: $ref: '#/components/schemas/ServiceMaintenance503' security: - bearerAuth: [] components: schemas: FileCreateRequestSerializerV3: type: object description: >- 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 properties: file: type: string format: uri description: The file to upload (binary data) filename: type: string description: Custom filename (defaults to uploaded filename if not provided) maxLength: 255 title: type: string description: >- Custom title for the document. If not provided, defaults to filename without extension. maxLength: 255 workspace_id: type: integer description: Workspace where the document will be stored. parser: type: string deprecated: true description: >- Deprecated — the platform always uses its default ingestion pipeline. This field is accepted but ignored. Will be removed in a future release. maxLength: 255 tags: type: array items: type: integer description: List of tag IDs to assign to the document on creation. external_metadata: oneOf: - $ref: '#/components/schemas/ExternalMetadataRequest' - type: 'null' description: >- 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). required: - file - workspace_id FileCreateResponseSerializerV3: type: object properties: id: type: integer readOnly: true filename: type: string readOnly: true description: Filename of the document workspace: oneOf: - $ref: '#/components/schemas/WorkspaceInFileResponseSerializerV3' - type: 'null' readOnly: true description: Workspace the document belongs to summaries: type: array items: $ref: '#/components/schemas/DocumentSummaryResponse' readOnly: true description: Document summaries (all languages) title: type: - string - 'null' maxLength: 255 extension: type: string description: File extension of the document status: $ref: '#/components/schemas/StatusEnum' status_vision: $ref: '#/components/schemas/StatusVisionEnum' created_at: type: string format: date-time description: Creation date of the resource updated_at: type: string format: date-time readOnly: true total_pages: type: integer readOnly: true description: Total number of pages tags: type: array items: $ref: '#/components/schemas/TagItem' readOnly: true description: List of tags associated with the document created_by: oneOf: - $ref: '#/components/schemas/CreatedBy' - type: 'null' readOnly: true description: >- User who created the file. Null when the file was created by the system. upload_session_uuid: type: - string - 'null' format: uuid readOnly: true description: Upload session UUID associated with this document external_metadata: oneOf: - $ref: '#/components/schemas/ExternalMetadataResponse' - type: 'null' description: External document metadata message: type: string readOnly: true description: Status message about the file upload required: - created_at - created_by - extension - external_metadata - filename - id - message - summaries - tags - total_pages - updated_at - upload_session_uuid - workspace APIV3ErrorResponse: type: object properties: id: type: - string - 'null' description: >- Job/resource id when one already exists (useful for async error diagnosis); null otherwise. code: type: integer description: HTTP status code error: type: string description: Error code used by the UI as a translation key detail: type: string description: Human-readable error message for developers doc_url: type: string description: Link to the error-code documentation page required: - code - detail - doc_url - error - id APIV3ValidationErrorResponse: type: object properties: id: type: - string - 'null' description: >- Job/resource id when one already exists (useful for async error diagnosis); null otherwise. code: type: integer description: HTTP status code error: type: string description: Error code used by the UI as a translation key detail: type: string description: Human-readable error message for developers doc_url: type: string description: Link to the error-code documentation page fields: type: object additionalProperties: type: array items: $ref: '#/components/schemas/APIV3FieldError' description: Field-level validation errors keyed by field name required: - code - detail - doc_url - error - id ServiceMaintenance503: type: object description: >- Returned by the maintenance middleware when the requested endpoint is blocked. required: - detail - error - mode properties: detail: type: string example: System is under maintenance. error: type: string example: service_maintenance mode: type: string enum: - full_shutdown - warning_banner description: >- `full_shutdown` blocks all traffic; `warning_banner` also blocks and shows a dismissible toast. reason: type: string description: Operator-supplied maintenance reason, if any. started_at: type: string format: date-time endpoint_category_names: type: array items: type: string description: >- Non-empty only for category-scoped periods. Empty means all endpoints are affected. ExternalMetadataRequest: type: object description: >- Validates external document metadata for V3 file endpoints. All fields are optional to support both creation (where doc_id is typically required - validated at the view level) and partial updates (all optional). properties: external_id: type: string description: >- External document ID in the source system. Required when creating external metadata for the first time. doc_type: type: string description: External document type (e.g. 'incident', 'page') additional_metadata: description: >- Arbitrary JSON object with extra information about the document (e.g. URL, version, timestamps). Passed through as-is. WorkspaceInFileResponseSerializerV3: type: object description: Minimal workspace info for file responses. properties: id: type: integer description: Workspace ID name: type: string description: Workspace name workspace_type: type: string description: Workspace type (shared or personal) required: - id - name - workspace_type DocumentSummaryResponse: type: object properties: language: allOf: - $ref: '#/components/schemas/LanguageEnum' description: |- Language of the summary. * `en` - English * `fr` - French * `es` - Spanish * `it` - Italian * `ar` - Arabic * `nl` - Dutch * `sv` - Swedish * `de` - German * `ja` - Japanese * `zh` - Chinese * `ko` - Korean summary: type: string description: Summary of the document. required: - summary StatusEnum: enum: - pending - pending_conversion - converting - parsing - parsing_failed - embedding - embedding_failed - embedded - parsed - fail - updating type: string description: |- * `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 StatusVisionEnum: enum: - pending - processing - embedded - fail - '-' type: string description: |- * `pending` - Pending * `processing` - Processing * `embedded` - Embedded * `fail` - Fail * `-` - Not available TagItem: type: object description: Serializer for tag items in file list response. properties: id: type: integer description: Tag ID name: type: string description: Tag name auto_assigned: type: boolean description: >- True if this tag was automatically assigned by the system, False if manually assigned by a user required: - auto_assigned - id - name CreatedBy: type: object description: Shallow user object for the file creator. properties: id: type: integer description: User ID first_name: type: string description: First name last_name: type: string description: Last name username: type: string description: Username required: - first_name - id - last_name - username ExternalMetadataResponse: type: object properties: external_id: type: string description: External document ID doc_type: type: string description: External document type additional_metadata: description: Additional metadata associated with the document required: - additional_metadata - doc_type - external_id APIV3FieldError: type: object properties: error: type: string description: Error code / translation key detail: type: string description: Human-readable description of the field error required: - detail - error LanguageEnum: enum: - en - fr - es - it - ar - nl - sv - de - ja - zh - ko type: string description: |- * `en` - English * `fr` - French * `es` - Spanish * `it` - Italian * `ar` - Arabic * `nl` - Dutch * `sv` - Swedish * `de` - German * `ja` - Japanese * `zh` - Chinese * `ko` - Korean securitySchemes: bearerAuth: type: http scheme: bearer description: >- Bearer authentication header of the form `Bearer `, where `` is your auth token. ````