> ## 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. # 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/openapi-v3.yaml patch /api/v3/files/{id} 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/{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 summary: File updated successfully FileUpdatedWithExternalMetadata: value: id: 124 filename: SRV-456789.pdf workspace: id: 1 name: Engineering Team summaries: [] title: ServiceNow Incident 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: SRV-456789 doc_type: incident additional_metadata: external_url: https://servicenow.example.com/incident/SRV-456789 last_synced_at: '2024-01-15T10:00:00Z' 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: allOf: - $ref: '#/components/schemas/ExternalMetadata' nullable: true 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: 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 size: type: integer nullable: true 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: 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 signature: type: string nullable: true readOnly: true description: TLSH hash for duplicate detection. content: type: string nullable: true description: >- Full text content of the document. Only included when include_content=true query parameter is provided. status_detail: type: string nullable: true description: >- Detailed error information. Only present when document processing has failed. parser: type: string nullable: true description: >- Parser/ingestion pipeline used for document processing (e.g., 'v2.1', 'v3.0'). external_metadata: allOf: - $ref: '#/components/schemas/ExternalMetadata' description: External document metadata required: - created_at - created_by - extension - external_metadata - filename - id - signature - size - 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. ````