> ## 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. # List files accessible to the authenticated user > Retrieve a paginated list of files (documents) accessible to the authenticated user. Results are ordered by upload date (newest first) by default. When using the `search` parameter, results are ordered by relevance. ## OpenAPI ````yaml /api-reference/api-console.yaml get /api/v3/files openapi: 3.1.0 info: title: LightOn API version: 3.9.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: Models description: >- List, register, update, and delete custom ML models scoped to your company. paths: /api/v3/files: get: tags: - Files summary: List files accessible to the authenticated user description: >- Retrieve a paginated list of files (documents) accessible to the authenticated user. Results are ordered by upload date (newest first) by default. When using the `search` parameter, results are ordered by relevance. operationId: api_v3_files_list parameters: - in: query name: attribute schema: type: string description: >- [Facet] Filter by attribute value. **Repeated `attribute` entries are ANDed; values inside one entry are ORed with `|`** (pipe is the recommended OR delimiter — comma also works but can be ambiguous with multi-key values). Example: `attribute=fiscal_year:2024|2025&attribute=status:active` → (fiscal_year 2024 OR 2025) AND (status active). Formats: `name` (has any value), `name:value` (exact), `name:>value` / `name:>=value` (gt/gte), `name:2024-01-01 summary: Date lower bound DateYearFilter: value: filing_date:2023 summary: Date year filter DateYear-monthFilter: value: filing_date:2023-06 summary: Date year-month filter NumericLowerBound: value: contract_value:>50000 summary: Numeric lower bound Multi-selectMembership: value: jurisdiction:FR summary: Multi-select membership Multi-selectOR: value: jurisdiction:FR|US summary: Multi-select OR ScopedToContentType: value: content_type(legal:compliance).regulation:AML summary: Scoped to content type AND-of-ORs(repeatParam): value: fiscal_year:2024|2025 summary: AND-of-ORs (repeat param) description: >- Repeat attribute for AND logic across different attributes. Each param's values are ORed. Use pipe (|) as the OR delimiter to avoid ambiguity with comma. - in: query name: content_type schema: type: string description: >- [Facet] Filter by content type path. Multiple values are OR. Exact-or-subtree matching by default (e.g. `legal` matches legal, legal:contract). Wildcards: `*contract*` (contains), `legal:contract*` (prefix). examples: EmptySample: value: '' summary: Empty sample LegalNDASample: value: legal:contract:nda summary: Legal NDA sample TechDesignDocSample: value: tech:specification:design-doc summary: Tech design doc sample BothSampleRecords: value: legal:contract:nda,tech:specification:design-doc summary: Both sample records ContainsContract: value: '*contract*' summary: Contains contract TechSpecificationSubtree: value: tech:specification* summary: Tech specification subtree - in: query name: created_at_after schema: type: string format: date-time description: >- Filter by created_at date range (inclusive, date-only strings treated as 00:00:00, e.g., ?created_at_after=2024-01-01&created_at_before=2024-01-01T23:59:59) - in: query name: created_at_before schema: type: string format: date-time description: >- Filter by created_at date range (inclusive, date-only strings treated as 00:00:00, e.g., ?created_at_after=2024-01-01&created_at_before=2024-01-01T23:59:59) - in: query name: extension schema: type: string description: >- Filter by file extensions (comma-separated, e.g., ?extension=pdf,docx) - in: query name: external_metadata__doc_type schema: type: string description: >- Filter by external document type (case-insensitive partial match). Only returns documents that have external metadata. Example: ?external_metadata__doc_type=gitlab matches 'gitlab issue', 'gitlab ticket', 'Gitlab MR', etc. - in: query name: external_metadata__external_id schema: type: string description: >- Filter by external document ID (exact match). Matches the doc_id stored in the document's external metadata. Only returns documents that have external metadata. Example: ?external_metadata__external_id=SN-12345 - in: query name: filename schema: type: string description: Filter by filename (case-insensitive partial match) - in: query name: group_id schema: type: string description: Filter by group IDs (comma-separated, e.g., ?group_id=1,2,3) - in: query name: include_details schema: type: boolean description: >- Include detail fields (e.g., TLSH signature, parser, summaries, and content type attribute values). Default: false. - in: query name: max_documents schema: type: integer description: >- Maximum number of documents to return (default: 50, minimum: 1, maximum: 500) - in: query name: ordering schema: type: string description: >- Sort results by field. Prefix with '-' for descending order. Allowed fields: created_at, filename, title, total_pages, size. Default: -created_at (newest first). Ignored when 'search' is provided (results ordered by relevance). - in: query name: owner_id schema: type: string description: Filter by owner user IDs (comma-separated, e.g., ?owner_id=1,2,3) - name: page required: false in: query description: A page number within the paginated result set. schema: type: integer - name: page_size required: false in: query description: Number of results to return per page. schema: type: integer - in: query name: search schema: type: string description: >- Optional semantic search query. When provided, results are ordered by relevance. - in: query name: search_details schema: type: boolean description: >- When true (and search is provided), include top relevant chunk(s) per document. - in: query name: search_details_chunks_limit schema: type: integer description: >- Max number of relevant chunks to return per document when search_details=true (1-10, default: 3). - in: query name: status schema: type: string enum: - converting - embedded - embedding - embedding_failed - fail - parsed - parsing - parsing_failed - pending - pending_conversion - updating description: >- Filter by status values (comma-separated, e.g., ?status=pending,embedded) - in: query name: status_vision schema: type: string enum: - '-' - embedded - fail - pending - processing description: >- Filter by vision status values (comma-separated, e.g., ?status_vision=pending,embedded) - in: query name: tag_id schema: type: string description: Filter by tag IDs (comma-separated, e.g., ?tag_id=1,2,3) - in: query name: title schema: type: string description: Filter by title (case-insensitive partial match) - in: query name: total_pages_max schema: type: - integer - 'null' maximum: 2147483647 minimum: -2147483648 description: >- Filter by total pages range (e.g., ?total_pages_min=10&total_pages_max=50) - in: query name: total_pages_min schema: type: - integer - 'null' maximum: 2147483647 minimum: -2147483648 description: >- Filter by total pages range (e.g., ?total_pages_min=10&total_pages_max=50) - in: query name: updated_at_after schema: type: string format: date-time description: >- Filter by updated_at date range (inclusive, date-only strings treated as 00:00:00, e.g., ?updated_at_after=2024-01-01&updated_at_before=2024-01-01T23:59:59) - in: query name: updated_at_before schema: type: string format: date-time description: >- Filter by updated_at date range (inclusive, date-only strings treated as 00:00:00, e.g., ?updated_at_after=2024-01-01&updated_at_before=2024-01-01T23:59:59) - in: query name: upload_session_uuid schema: type: string description: >- Filter by upload session UUID (e.g., ?upload_session_uuid=123e4567-e89b-12d3-a456-426614174000) - in: query name: workspace_id schema: type: string description: Filter by workspace IDs (comma-separated, e.g., ?workspace_id=1,2,3) responses: '200': content: application/json: schema: $ref: '#/components/schemas/PaginatedFileListResponseSerializerV3List' examples: DefaultCompactResponse: value: count: 123 next: http://api.example.org/accounts/?page=4 previous: http://api.example.org/accounts/?page=2 results: - - id: 124 filename: customer_nda.pdf workspace: id: 3 name: Legal Team workspace_type: shared summaries: [] title: Customer NDA extension: pdf status: embedded status_vision: embedded created_at: '2024-01-14T14:20:00Z' updated_at: '2024-01-14T14:22:00Z' total_pages: 8 tags: - id: 7 name: confidential auto_assigned: true - id: 12 name: Q1-2026 auto_assigned: false created_by: id: 42 first_name: Jane last_name: Doe username: jdoe external_metadata: external_id: legal-doc-456789 doc_type: nda additional_metadata: external_url: https://contracts.example.com/legal/customer-nda content_types: - path: legal:contract:nda label: Non-Disclosure Agreement - id: 123 filename: design_doc.pdf workspace: id: 1 name: Engineering Team workspace_type: shared summaries: - language: en summary: This document outlines Q4 initiatives... title: Retrieval Service Design Document extension: pdf status: embedded status_vision: embedded created_at: '2024-01-15T10:30:00Z' updated_at: '2024-01-15T10:35:00Z' total_pages: 25 size: 2458624 tags: - id: 10 name: Project X auto_assigned: false created_by: id: 42 first_name: Jane last_name: Doe username: jdoe content_types: [] summary: Default compact response description: >- Compact content types (path and label only — no attribute values). Null fields omitted. WithIncludeDetails=true(mid-expanded): value: count: 123 next: http://api.example.org/accounts/?page=4 previous: http://api.example.org/accounts/?page=2 results: - - id: 124 filename: customer_nda.pdf workspace: id: 3 name: Legal Team workspace_type: custom summaries: - language: en summary: >- Non-disclosure agreement between LightOn and Nimbus Labs. title: Customer NDA extension: pdf status: embedded status_vision: embedded created_at: '2024-01-14T14:20:00Z' updated_at: '2024-01-14T14:22:00Z' total_pages: 8 tags: - id: 7 name: confidential auto_assigned: true - id: 12 name: Q1-2026 auto_assigned: false created_by: id: 42 first_name: Jane last_name: Doe username: jdoe signature: T1A1B2C3D4E5F6G7H8I9J0K1L2M3N4O5P6Q7R8S9T0U1V2 parser: v2.2.1 content_types: - code: nda path: legal:contract:nda label: Non-Disclosure Agreement breadcrumb: - code: legal path: legal label: Legal - code: contract path: legal:contract label: Contract - code: nda path: legal:contract:nda label: Non-Disclosure Agreement attribute_values: jurisdiction: value: - FR - US type: multi-select label: Jurisdiction is_mutual: value: true type: boolean label: Is Mutual summary: With include_details=true (mid-expanded) description: >- Adds summaries, signature, parser. Content types gain code, structured breadcrumb (ancestor chain with code/path/label per node), and attribute values. Attribute values use compact format (no schema metadata). WithSearch+SearchDetails=true: value: count: 123 next: http://api.example.org/accounts/?page=4 previous: http://api.example.org/accounts/?page=2 results: - - id: 123 filename: design_doc.pdf workspace: id: 1 name: Engineering Team workspace_type: shared summaries: - language: en summary: This document outlines Q4 initiatives... title: Retrieval Service Design Document extension: pdf status: embedded status_vision: embedded created_at: '2024-01-15T10:30:00Z' updated_at: '2024-01-15T10:35:00Z' total_pages: 25 size: 2458624 tags: - id: 10 name: Project X auto_assigned: false created_by: id: 42 first_name: Jane last_name: Doe username: jdoe content_types: - path: tech:specification:design-doc label: Design Document search_details: relevant_chunks: - text: >- This paragraph is a representative excerpt of the highest-ranked chunk. chunk_type: text score: 1.84 scores: text: 0.82 vision: null keyword: 0.71 multivector: 0.6 relevance: null summary: With search + search_details=true description: >- When search is active with search_details=true, each file includes relevant chunks. ListOfFiles(withIncludeDetails=true): value: count: 123 next: http://api.example.org/accounts/?page=4 previous: http://api.example.org/accounts/?page=2 results: - - id: 123 filename: design_doc.pdf workspace: id: 1 name: Engineering Team workspace_type: shared summaries: - language: en summary: This document outlines Q4 initiatives... title: Retrieval Service Design Document extension: pdf status: embedded status_vision: embedded created_at: '2024-01-15T10:30:00Z' updated_at: '2024-01-15T10:35:00Z' total_pages: 25 size: 2458624 tags: [] created_by: id: 42 first_name: Jane last_name: Doe username: jdoe signature: >- T1A1B2C3D4E5F6G7H8I9J0K1L2M3N4O5P6Q7R8S9T0U1V2W3X4Y5Z6A7B8C9D0E1F2 parser: v2.2.1 content_types: - path: tech:specification:design-doc label: Design Document attributes: - name: owner_team label: Owner Team value: Platform Engineering type: text - name: maturity label: Maturity value: Approved type: select - name: component label: Component value: Document Retrieval Service type: text - id: 124 filename: customer_nda.pdf workspace: id: 3 name: Legal Team workspace_type: shared summaries: [] title: Customer NDA extension: pdf status: embedded status_vision: embedded created_at: '2024-01-14T14:20:00Z' updated_at: '2024-01-14T14:22:00Z' total_pages: 8 tags: [] created_by: id: 43 first_name: John last_name: Smith username: jsmith signature: >- T1B2C3D4E5F6G7H8I9J0K1L2M3N4O5P6Q7R8S9T0U1V2W3X4Y5Z6A7B8C9D0E1F2G3 parser: v2.2.1 content_types: - path: legal:contract:nda label: Non-Disclosure Agreement attributes: - name: jurisdiction label: Jurisdiction value: - FR - US type: multi_select - name: confidentiality_level label: Confidentiality Level value: Confidential type: select - name: parties label: Parties value: LightOn, Nimbus Labs type: text - name: contract_status label: Contract Status value: Executed type: select - name: counterparty label: Counterparty value: Nimbus Labs type: text - name: is_mutual label: Is Mutual value: true type: boolean summary: List of files (with include_details=true) description: List of files accessible to the authenticated user '401': description: Authentication failed - missing or invalid API key '403': description: Permission denied '404': description: Not found '429': description: Too many requests - rate limit exceeded security: - bearerAuth: [] components: schemas: PaginatedFileListResponseSerializerV3List: type: object required: - count - results properties: count: type: integer example: 123 next: type: string nullable: true format: uri example: http://api.example.org/accounts/?page=4 previous: type: string nullable: true format: uri example: http://api.example.org/accounts/?page=2 results: type: array items: $ref: '#/components/schemas/FileListResponseSerializerV3' FileListResponseSerializerV3: 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_detail: type: - string - 'null' description: >- Detailed error information. Only present when document processing has failed. 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 size: type: - integer - 'null' readOnly: true description: Size of the file in bytes. 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 search_details: oneOf: - $ref: '#/components/schemas/SearchDetails' - type: 'null' readOnly: true description: Only present when search_details=true and search is provided. signature: type: - string - 'null' readOnly: true description: >- TLSH hash for duplicate detection. Only included when include_details=true (detail field). parser: type: - string - 'null' description: >- Parser/ingestion pipeline used for document processing (e.g., 'v2.1', 'v3.0'). Only included when include_details=true (detail field). external_metadata: allOf: - $ref: '#/components/schemas/ExternalMetadataResponse' description: External document metadata content_types: type: array items: $ref: '#/components/schemas/DocumentFacetCompactSchema' readOnly: true description: >- Facet content types with nested attribute values. Excludable via ?exclude=content_types. required: - content_types - created_at - created_by - extension - filename - id - tags - total_pages - updated_at - upload_session_uuid - workspace 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 SearchDetails: type: object description: Serializer for search details in file list response. properties: relevant_chunks: type: array items: $ref: '#/components/schemas/RelevantChunkScoredV3' description: Relevant chunks ordered by score descending required: - relevant_chunks 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 DocumentFacetCompactSchema: type: object description: >- OpenAPI schema for compact content type response (Tier 1 — list default). properties: path: type: string description: Colon-separated content type path (e.g. legal:contract:nda) label: type: string description: User-readable label (leaf node) attribute_values: type: object additionalProperties: $ref: '#/components/schemas/DocumentFacetAttributeValueSchema' description: >- Map of attribute name to {value, type}. Only present when include_details=true. required: - label - path 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 RelevantChunkScoredV3: type: object description: >- Relevant chunk with the unified scoring shape, aligned with /api/v3/search. Exposes ``score`` + ``scores`` (text/vision/keyword/multivector/relevance) instead of the legacy final_score/lexical_score/distance. ``scores.relevance`` is always null on this path — DocFinder (doc-level file search) runs no cross-encoder. properties: text: type: string description: Chunk text content chunk_type: type: string description: Chunk type (e.g. text/table) score: type: number format: double readOnly: true description: Overall fused relevance score (higher is better) scores: allOf: - $ref: '#/components/schemas/_ChunkScoresSchema' readOnly: true required: - score - scores - text DocumentFacetAttributeValueSchema: type: object description: OpenAPI schema for a compact attribute value entry. properties: value: description: Attribute value (type depends on attribute definition) type: type: string description: Attribute type (text, number, date, boolean, select, multi_select) label: type: string description: User-readable attribute label (present when include_details=true) required: - type - value _ChunkScoresSchema: type: object description: >- Per-signal score breakdown. Schema for OpenAPI; higher is better; null = not computed. ``text``/``vision`` are 0..1 similarities; ``keyword`` (BM25) and ``multivector`` (ColBERT) are raw scores, not bounded to 0..1. Same shape as /api/v3/search and /retrieve. ``relevance`` (cross-encoder) is always null on the file-search path — DocFinder runs no cross-encoder. Defined locally to avoid a circular import with the /retrieve serializer module. properties: text: type: - number - 'null' format: double description: >- Dense text embedding similarity (1 - distance), 0..1. Null in vision mode. vision: type: - number - 'null' format: double description: >- Vision page similarity, 0..1. Null when the document has no vision index. keyword: type: - number - 'null' format: double description: BM25 lexical score (raw, not 0..1). Null in vision mode. multivector: type: - number - 'null' format: double description: >- ColBERT multi-vector (MaxSim) score (raw, not 0..1). Null when multi-vector reranking is disabled. relevance: type: - number - 'null' format: double description: >- Cross-encoder reranker confidence. Always null on file search — DocFinder runs no cross-encoder. required: - keyword - multivector - relevance - text - vision securitySchemes: bearerAuth: type: http scheme: bearer description: >- Bearer authentication header of the form `Bearer `, where `` is your auth token. ````