Update file metadata or replace its file

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
• file: Replace the original file and re-ingest the document

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
• external_id cannot be changed on a document imported from a datasource: the sync matches its documents on it, so a rename would detach the document from its source. doc_type and additional_metadata stay editable

File replacement behavior:

• The document keeps its id, title, manually assigned tags, content types, attribute values and external metadata. Only the file and everything derived from it (text, chunks, embeddings, auto-assigned tags, summaries) are rebuilt.
• Any supported file type is accepted, including one that differs from the current file — the processing statuses are re-derived from the new file.
• Replacing the file additionally requires an owner or editor role in the document’s workspace, and is not available in workspaces configured for synced documents.
• The storage quota is checked on the size difference, not the full new size.
• file can be combined with title, tags and external_metadata in the same request: the metadata changes apply immediately, the file is queued.
• The response reflects the document as it still is: filename, extension, size, total_pages, status, signature, summaries and content describe the previous file until re-ingestion begins. The document keeps serving its previous content — search, extracts and download stay consistent — and leaves the search index only once processing actually starts.
• pending_reprocess is set to update on the response and on subsequent reads, and is the only signal that the queued file has not been processed yet: status still reports the previous run’s outcome (typically Embedded) until the pipeline picks the document up. Poll until pending_reprocess is null and status is terminal — treating a terminal status alone as completion reports success against the previous file.
• Sending a new file while one is already queued replaces the queued file, and a file replacement supersedes any other reprocessing already queued for the document: the most recent request is always the one that goes live.
• Once re-ingestion starts, a document whose new file needs rendering has no rendered PDF until conversion completes. download?purpose=rendered_pdf serves the original during that window, as it does for any file still being converted, so a viewer can receive a non-PDF body. Gate the viewer on status rather than on the download succeeding.
• The request is applied in full or not at all: tags are validated before the file is queued, so an invalid tag id rejects the whole request without staging anything.

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 a public-dataset file but is refused permission to edit it — public datasets are read-only.