---
title: "Update file metadata"
method: PATCH
path: "/api/v3/files/{id}"
tags: ["Files"]
---

# Update file metadata

`PATCH /api/v3/files/{id}`

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

**Public datasets:** editing a public-dataset file requires the instance-admin `MANAGE_PUBLIC_DATASET` permission. A workspace-scoped API key with read access (company opted in via `allow_access_to_public_datasets`) can see the file but gets 403, not 404, when attempting to edit it — public datasets are read-only.

## Path parameters

- `id` integer, required

## Response `200`

File updated successfully

- FileRetrieveResponseSerializerV3
  - `id` integer, required
  - `filename` string, required — Filename of the document
  - `workspace` WorkspaceInFileResponseSerializerV3, required — Minimal workspace info for file responses.
    - `id` integer, required — Workspace ID
    - `name` string, required — Workspace name
    - `workspace_type` string, required — Workspace type (shared or personal)
  - `summaries` DocumentSummaryResponse[], required — Document summaries (all languages)
    - `language` 'en' | 'fr' | 'es' | 'it' | 'ar' | 'nl' | 'sv' | 'de' | 'ja' | 'zh' | 'ko' — * `en` - English * `fr` - French * `es` - Spanish * `it` - Italian * `ar` - Arabic * `nl` - Dutch * `sv` - Swedish * `de` - German * `ja` - Japanese * `zh` - Chinese * `ko` - Korean
    - `summary` string, required — Summary of the document.
  - `title` string, nullable
  - `extension` string, required — File extension of the document
  - `status` 'pending' | 'pending_conversion' | 'converting' | 'parsing' | 'parsing_failed' | 'embedding' | 'embedding_failed' | 'embedded' | 'parsed' | 'fail' | 'updating' — * `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
  - `status_vision` 'pending' | 'processing' | 'embedded' | 'fail' | '-' — * `pending` - Pending * `processing` - Processing * `embedded` - Embedded * `fail` - Fail * `-` - Not available
  - `created_at` string, date-time, required — Creation date of the resource
  - `updated_at` string, date-time, required
  - `total_pages` integer, required — Total number of pages
  - `size` integer, nullable — Size of the file in bytes.
  - `tags` TagItem[], required — List of tags associated with the document
    - `id` integer, required — Tag ID
    - `name` string, required — Tag name
    - `auto_assigned` boolean, required — True if this tag was automatically assigned by the system, False if manually assigned by a user
  - `created_by` CreatedBy, required — Shallow user object for the file creator.
    - `id` integer, required — User ID
    - `first_name` string, required — First name
    - `last_name` string, required — Last name
    - `username` string, required — Username
  - `upload_session_uuid` string, uuid, nullable, required — Upload session UUID associated with this document
  - `signature` string, nullable, required — TLSH hash for duplicate detection.
  - `content` string, nullable — 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` Page[] — 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.
    - `index` integer, required — Page number within the document (1-based).
    - `markdown` string, required — Page text rendered as Markdown.
  - `status_detail` string, nullable — Detailed error information. Only present when document processing has failed.
  - `parser` string, nullable — Parser/ingestion pipeline used for document processing (e.g., 'v2.1', 'v3.0').
  - `external_metadata` ExternalMetadataResponse
    - `external_id` string, required — External document ID
    - `doc_type` string, required — External document type
    - `additional_metadata` unknown, required
  - `content_types` DocumentFacetCompactSchema[], required — Facet content types with nested attribute values. Excludable via ?exclude=content_types.
    - `path` string, required — Colon-separated content type path (e.g. legal:contract:nda)
    - `label` string, required — User-readable label (leaf node)
    - `attribute_values` object — Map of attribute name to {value, type}. Only present when include_details=true.

## Other responses

- `400` — Validation error
- `401` — Authentication credentials were not provided
- `404` — File not found or not accessible

---

[API](https://skmtc.net/lighton/apis/lighton-api.md) · [All operations](https://skmtc.net/lighton/apis/lighton-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/lighton/lighton-api/versions/86c57e94ef15/schema)