> ## 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. # Retrieve a single file by ID > Retrieve detailed information for a single file by its ID. Only files that the authenticated user is authorized to access will be returned. Returns 404 if the file does not exist or the user does not have access. Query Parameters: - include_content: Set to 'true' to include the full text content of the document (default: false) The response includes comprehensive document details including: - Basic metadata (id, filename, title, extension, dates, page count) - Full text content of the document (only when include_content=true) - Processing status (status, status_vision, status_detail if failed) - Associated tags and workspace information - File size (if available) - Parser/ingestion pipeline (if available, after parsing starts) - Signature (TLSH hash for duplicate detection) - Facet content types and nested attribute values (full expanded with attribute definitions) ## OpenAPI ````yaml /api-reference/api-console.yaml get /api/v3/files/{id} 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/{id}: get: tags: - Files summary: Retrieve a single file by ID description: >- Retrieve detailed information for a single file by its ID. Only files that the authenticated user is authorized to access will be returned. Returns 404 if the file does not exist or the user does not have access. Query Parameters: - include_content: Set to 'true' to include the full text content of the document (default: false) The response includes comprehensive document details including: - Basic metadata (id, filename, title, extension, dates, page count) - Full text content of the document (only when include_content=true) - Processing status (status, status_vision, status_detail if failed) - Associated tags and workspace information - File size (if available) - Parser/ingestion pipeline (if available, after parsing starts) - Signature (TLSH hash for duplicate detection) - Facet content types and nested attribute values (full expanded with attribute definitions) operationId: api_v3_files_retrieve parameters: - in: path name: id schema: type: integer description: A unique integer value identifying this Document. required: true - in: query name: include_content schema: type: boolean description: >- When true, include the full text content of the document in the response (default: false). Recommended to only enable when needed as content can be large. responses: '200': content: application/json: schema: $ref: '#/components/schemas/FileRetrieveResponseSerializerV3' examples: FileDetail(fullExpanded): value: 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 external_metadata: external_id: legal-doc-456789 doc_type: nda additional_metadata: external_url: https://contracts.example.com/legal/customer-nda 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 attribute: name: jurisdiction label: Jurisdiction type: multi-select required: true choices: - FR - US - UK - DE is_mutual: value: true type: boolean attribute: name: is_mutual label: Is Mutual type: boolean required: false counterparty: value: Nimbus Labs type: text attribute: name: counterparty label: Counterparty type: text required: false summary: File detail (full expanded) description: >- Detail always includes summaries, signature, and full expanded content types with code, breadcrumb, and attribute definitions (type, required, choices). FileDetailWithContent: value: id: 123 filename: design_doc.pdf workspace: id: 1 name: Engineering Team workspace_type: custom 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 signature: T1A1B2C3D4E5F6G7H8I9J0K1L2M3N4O5P6Q7R8S9T0U1V2 content: >- Retrieval Service Design Document Overview This document outlines the service architecture, retrieval flow, and implementation decisions... pages: - index: 1 markdown: |- # Retrieval Service Design Document ## Overview ... - index: 2 markdown: |- ## Retrieval flow ... content_types: - code: design-doc path: tech:specification:design-doc label: Design Document breadcrumb: - code: tech path: tech label: Tech - code: specification path: tech:specification label: Specification - code: design-doc path: tech:specification:design-doc label: Design Document attribute_values: maturity: value: Approved type: select label: Maturity attribute: name: maturity label: Maturity type: select required: true choices: - Draft - In Review - Approved - Deprecated owner_team: value: Platform Engineering type: text label: Owner Team attribute: name: owner_team label: Owner Team type: text required: false summary: File detail with content description: >- With include_content=true, the full document text is included as the flat `content` string and as canonical per-page objects under `pages` (`{ index, markdown }`, the same shape returned by /parse and /ocr). `content` is retained for now; prefer `pages`. description: >- Detailed file information. Always uses full expanded content types (Tier 3) with breadcrumb, code, and attribute definitions including type, required, and choices. '401': description: Authentication failed - missing or invalid API key '404': description: File not found or not accessible security: - bearerAuth: [] components: schemas: FileRetrieveResponseSerializerV3: 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 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 signature: type: - string - 'null' readOnly: true description: TLSH hash for duplicate detection. content: type: - string - 'null' deprecated: true readOnly: true description: >- Deprecated — use `pages[]` instead. Full text content of the document, derived from per-page text, as a single flat string. Only included when include_content=true query parameter is provided. Will be removed in a future release. pages: type: array items: $ref: '#/components/schemas/Page' readOnly: true description: >- Per-page document text in the canonical `{ index, markdown }` shape shared with /parse and /ocr. Only included when include_content=true. Intended replacement for the flat `content` string. For documents ingested before per-page text was stored, the full `content` is returned as a single page (index 1); empty only when there is no content at all. status_detail: type: - string - 'null' description: >- Detailed error information. Only present when document processing has failed. parser: type: - string - 'null' description: >- Parser/ingestion pipeline used for document processing (e.g., 'v2.1', 'v3.0'). 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 - signature - summaries - 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 Page: type: object description: >- Canonical per-page document text object. Originates with /parse and is reused by /ocr and /files (the latter imports it from here) so a client can switch between live parsing and reading an already-ingested file without reshaping page data. Defined once and reused everywhere — never redefine this shape per app. Extensible: future per-page fields (tables, images, confidence, ...) can be added here without breaking callers that only consume ``index`` + ``markdown``. properties: index: type: integer description: Page number within the document (1-based). markdown: type: string description: Page text rendered as Markdown. required: - index - markdown 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 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 securitySchemes: bearerAuth: type: http scheme: bearer description: >- Bearer authentication header of the form `Bearer `, where `` is your auth token. ````