> ## 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. # Update file metadata > Update mutable fields of a file (document). **Updatable fields:** - `title`: Update the document title - `tags`: Replace ALL tags for the document (both manual and auto-assigned) - `external_metadata`: Create or update external source metadata **Tag replacement behavior:** - Providing a tags array replaces ALL existing tags (manual and auto-assigned) - To remove all tags, send `[0]` (sentinel value for multipart format) - Omitting `tags` field leaves tags unchanged - New tags are marked as manually assigned (`auto_assigned=False`) **External metadata behavior:** - When creating for the first time, `external_id` is required - When updating existing metadata, `external_id` is optional (existing value is preserved) - Fields in `additional_metadata` are merged (not replaced) with existing values **Validation:** - Returns 400 if only immutable fields are provided (mutable fields: 'external_metadata', 'tags', 'title') - Returns 400 if tag IDs are invalid or don't belong to user's company - Returns 404 if document doesn't exist or user doesn't have access ## OpenAPI ````yaml /api-reference/api-console.yaml patch /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}: patch: tags: - Files summary: Update file metadata description: > Update mutable fields of a file (document). **Updatable fields:** - `title`: Update the document title - `tags`: Replace ALL tags for the document (both manual and auto-assigned) - `external_metadata`: Create or update external source metadata **Tag replacement behavior:** - Providing a tags array replaces ALL existing tags (manual and auto-assigned) - To remove all tags, send `[0]` (sentinel value for multipart format) - Omitting `tags` field leaves tags unchanged - New tags are marked as manually assigned (`auto_assigned=False`) **External metadata behavior:** - When creating for the first time, `external_id` is required - When updating existing metadata, `external_id` is optional (existing value is preserved) - Fields in `additional_metadata` are merged (not replaced) with existing values **Validation:** - Returns 400 if only immutable fields are provided (mutable fields: 'external_metadata', 'tags', 'title') - Returns 400 if tag IDs are invalid or don't belong to user's company - Returns 404 if document doesn't exist or user doesn't have access operationId: api_v3_files_partial_update parameters: - in: path name: id schema: type: integer description: A unique integer value identifying this Document. required: true requestBody: content: multipart/form-data: schema: $ref: '#/components/schemas/PatchedFileUpdateRequestSerializerV3' examples: UpdateTitleOnly: value: title: Updated Document Title summary: Update title only description: Update only the document title ReplaceAllTags: value: tags: - 1 - 2 summary: Replace all tags description: >- Replace all existing tags (both manual and auto-assigned) with new ones. Tags can be sent as a JSON array string (e.g., '[1,2]') or as multiple form fields with the same name. RemoveAllTags: value: tags: - 0 summary: Remove all tags description: Remove all tags using sentinel value [0] CreateExternalMetadata: value: external_metadata: external_id: gitlab-issue-456 doc_type: gitlab_issue additional_metadata: external_url: https://gitlab.example.com/project/-/issues/456 name: Fix authentication bug summary: Create external metadata description: >- Attach external source metadata to a document that has none yet. `external_id` is required for creation. `external_metadata` must be sent as a JSON string when using multipart/form-data. UpdateExistingExternalMetadata: value: external_metadata: additional_metadata: last_synced_at: '2024-01-15T10:00:00Z' name: Updated Name summary: Update existing external metadata description: >- Update fields on an existing external metadata record. `external_id` is optional when a record already exists — it will be preserved if omitted. Fields inside `additional_metadata` are merged with existing values, not replaced. application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/PatchedFileUpdateRequestSerializerV3' examples: UpdateTitleOnly: value: title: Updated Document Title summary: Update title only description: Update only the document title ReplaceAllTags: value: tags: - 1 - 2 summary: Replace all tags description: >- Replace all existing tags (both manual and auto-assigned) with new ones. Tags can be sent as a JSON array string (e.g., '[1,2]') or as multiple form fields with the same name. RemoveAllTags: value: tags: - 0 summary: Remove all tags description: Remove all tags using sentinel value [0] CreateExternalMetadata: value: external_metadata: external_id: gitlab-issue-456 doc_type: gitlab_issue additional_metadata: external_url: https://gitlab.example.com/project/-/issues/456 name: Fix authentication bug summary: Create external metadata description: >- Attach external source metadata to a document that has none yet. `external_id` is required for creation. `external_metadata` must be sent as a JSON string when using multipart/form-data. UpdateExistingExternalMetadata: value: external_metadata: additional_metadata: last_synced_at: '2024-01-15T10:00:00Z' name: Updated Name summary: Update existing external metadata description: >- Update fields on an existing external metadata record. `external_id` is optional when a record already exists — it will be preserved if omitted. Fields inside `additional_metadata` are merged with existing values, not replaced. responses: '200': content: application/json: schema: $ref: '#/components/schemas/FileRetrieveResponseSerializerV3' examples: FileUpdatedSuccessfully: value: id: 123 filename: project_proposal.pdf workspace: id: 1 name: Engineering Team summaries: - language: en summary: This document outlines Q4 initiatives... title: Updated Document Title extension: pdf status: embedded status_vision: embedded created_at: '2024-01-15T10:30:00Z' updated_at: '2024-01-15T11:45:00Z' total_pages: 25 size: 2458624 tags: - id: 1 name: Compliance auto_assigned: false created_by: id: 42 first_name: Jane last_name: Doe username: jdoe signature: >- T1A1B2C3D4E5F6G7H8I9J0K1L2M3N4O5P6Q7R8S9T0U1V2W3X4Y5Z6A7B8C9D0E1F2 parser: v2.2.1 external_metadata: null content_types: - path: tech:specification:design-doc label: Design Document labels: - Tech - Specification - 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 summary: File updated successfully FileUpdatedWithExternalMetadata: value: id: 124 filename: customer_nda.pdf workspace: id: 3 name: Legal Team summaries: [] title: Customer NDA extension: pdf status: embedded status_vision: embedded created_at: '2024-01-15T10:30:00Z' updated_at: '2024-01-15T11:45:00Z' total_pages: 3 size: 102400 tags: [] created_by: id: 42 first_name: Jane last_name: Doe username: jdoe signature: >- T1A1B2C3D4E5F6G7H8I9J0K1L2M3N4O5P6Q7R8S9T0U1V2W3X4Y5Z6A7B8C9D0E1F2 external_metadata: external_id: legal-doc-456789 doc_type: nda additional_metadata: external_url: https://contracts.example.com/legal/customer-nda last_synced_at: '2024-01-15T10:00:00Z' content_types: - path: legal:contract:nda label: Non-Disclosure Agreement labels: - Legal - Contract - 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: File updated with external metadata description: File updated successfully '400': description: Validation error '401': description: Authentication credentials were not provided '404': description: File not found or not accessible security: - bearerAuth: [] components: schemas: PatchedFileUpdateRequestSerializerV3: type: object description: >- Request serializer for PATCH /api/v3/files/{id} endpoint. Allows partial updates to mutable document fields: - title: Update the document title - tags: Replace ALL tags for the document (both manual and auto-assigned) - external_metadata: Create or update external source metadata Immutable fields (if provided, will return 400): - file, filename, workspace_id, parser, etc. properties: title: type: string description: Updated title for the document. maxLength: 255 tags: type: array items: type: integer description: >- List of tag IDs to replace ALL existing tags (both manual and auto-assigned). To remove all tags when using multipart format, send [0] as the sentinel value. external_metadata: oneOf: - $ref: '#/components/schemas/ExternalMetadataRequest' - type: 'null' description: >- External source metadata to create or update. `external_id` is required when no external metadata record exists yet. Fields in `additional_metadata` are merged (not replaced) with existing values. 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 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 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. ````