Sign in

v1

latestOpenAPI 3.1.02026-07-263580186.3 KB
Files

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

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.

patch/api/v3/files/{id}

Path parameters

idinteger required

A unique integer value identifying this Document.

Response

File updated successfully

idinteger required
filenamestring required

Filename of the document

titlestring nullable
extensionstring 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_atstring date-time required

Creation date of the resource

updated_atstring date-time required
total_pagesinteger required

Total number of pages

sizeinteger nullable

Size of the file in bytes.

upload_session_uuidstring uuid nullable required

Upload session UUID associated with this document

signaturestring nullable required

TLSH hash for duplicate detection.

contentstring 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.

status_detailstring nullable

Detailed error information. Only present when document processing has failed.

parserstring nullable

Parser/ingestion pipeline used for document processing (e.g., 'v2.1', 'v3.0').