> ## Documentation Index > Fetch the complete documentation index at: https://docs.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. **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/openapi-v3.yaml post /api/v3/files openapi: 3.0.3 info: title: Paradigm API version: xenial-xerus (v3) description: >- A versatile and adaptable tool designed to integrate Generative AI into your applications servers: - url: https://paradigm.lighton.ai security: [] tags: - name: Agents description: Operations about agents - name: Threads description: Operations about agents conversation threads - name: Tools description: Operations about native tools - name: Models description: Operations about AI models - name: MCP description: Operations about MCP servers - name: Sources description: Operations about sources used by agents conversation threads - name: Artifacts description: Operations about artifacts generated by agents conversation threads - name: Agent description: >- Operations about agents (deprecated). Please use the 'Agents' API component instead. - name: Files description: Operations about files - name: Files Processing description: Operations about files processing - name: Tags description: Operations about tags - name: Workspaces description: Operations about workspaces - name: Users description: Operations about users - name: User Groups description: Operations about user groups - name: Companies description: Operations about companies - name: SCIM description: Operations about SCIM 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. **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 parser: v2.2.1 tags: - 1 - 2 summary: File upload with custom metadata and tags description: >- Upload a file with custom filename, title, parser, and manual tag assignment. The `parser` field only accepts `'v2.2.1'`; any other value is rejected. Omit it to use the platform default. Tags can be sent as a JSON array string (e.g., '[1,2]') or as multiple form fields with the same name. 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 parser: v2.2.1 tags: - 1 - 2 summary: File upload with custom metadata and tags description: >- Upload a file with custom filename, title, parser, and manual tag assignment. The `parser` field only accepts `'v2.2.1'`; any other value is rejected. Omit it to use the platform default. Tags can be sent as a JSON array string (e.g., '[1,2]') or as multiple form fields with the same name. 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: '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: custom 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: custom 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: custom 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: custom 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': description: Validation error '401': description: Authentication credentials were not provided '403': description: You do not have permission to perform this action '429': description: Too many concurrent uploads for this session 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: 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 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 description: >- Ingestion pipeline to use. Only 'v2.2.1' is accepted. If omitted, the platform default is used. maxLength: 255 tags: type: array items: type: integer description: List of tag IDs to assign to the document on creation. external_metadata: allOf: - $ref: '#/components/schemas/ExternalMetadata' nullable: true 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: allOf: - $ref: '#/components/schemas/WorkspaceInFileResponseSerializerV3' nullable: true 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 nullable: true maxLength: 255 extension: type: string description: File extension of the document status: $ref: '#/components/schemas/Status88dEnum' 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: allOf: - $ref: '#/components/schemas/CreatedBy' nullable: true readOnly: true description: >- User who created the file. Null when the file was created by the system. upload_session_uuid: type: string format: uuid nullable: true readOnly: true description: Upload session UUID associated with this document external_metadata: allOf: - $ref: '#/components/schemas/ExternalMetadata' 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 ExternalMetadata: 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 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 (company, personal, or custom) required: - id - name - workspace_type DocumentSummaryResponse: type: object properties: language: allOf: - $ref: '#/components/schemas/DocumentSummaryResponseLanguageEnum' 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 Status88dEnum: enum: - pending - parsing - parsing_failed - embedding - embedding_failed - embedded - fail - updating type: string description: |- * `pending` - Pending * `parsing` - Parsing * `parsing_failed` - Parsing Failed * `embedding` - Embedding * `embedding_failed` - Embedding Failed * `embedded` - Embedded * `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 DocumentSummaryResponseLanguageEnum: 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. ````