Replace the document with a new file
PUT/v1/knowledge_bases/:kb_id/documents/:document_id/file
Creates a new version of the document. The current ready version stays searchable until the new one is ready, then the switch is atomic. The temporary second copy is not billed as storage; processing the new file is billed. Only one replacement at a time (409 version_conflict). Version history is not exposed.
Access: API key scope knowledge:write; portal users: organization admins and owners; the knowledge base in the path must be on the key's access list; refused with 503 maintenance_mode during maintenance; refused with 403 module_disabled while knowledge bases are switched off on the platform.
Request
Responses
- 202
- 402
- 403
- 404
- 409
- 413
- 422
- 503
Replacement accepted; see pending_version.
trial_exhausted, insufficient_credits, credit_limit_exceeded, payg_spend_cap_exceeded, payment_suspended — details.price_card_url always set. After the free trial, knowledge bases are billed pay-as-you-go for every organization (from the prepaid wallet or on the postpaid invoice); no plan or commitment covers them.
scope_missing, kb_not_in_allowlist, role_insufficient, actor_not_permitted, tenant_suspended, module_disabled (knowledge bases switched off on the platform: an operation that creates data or starts processing, for an organization that still has knowledge bases), web_sources_disabled, domain_blocked, domain_not_verified (website sources)
not_found (absent or owned by another organization — identical), module_disabled
idempotency_key_conflict, idempotency_in_progress, version_conflict, duplicate_content, kb_suspended, kb_deleting, document_deleting, document_not_ready, invalid_document_state, trial_kb_frozen, resource_limit_reached, export_in_progress, source_sync_in_progress, invalid_source_state, duplicate_source
file_too_large, too_many_files, request_too_large
validation_failed, invalid_identifier, metadata_*, filter_invalid, query_too_long, batch_too_large, file-type codes, https_required, source_url_rejected, robots_disallowed, ai_signal_optout, attestation_required, terms_acceptance_required
maintenance_mode, knowledge_unavailable, retrieval_unavailable, billing_unavailable — Retry-After header set