curl --request PATCH \
--url https://{host}/v2/workspaces/slug:storage/webhooks/v1/knowledge_bases/{knowledgeBaseId}/documents/{documentId} \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"tags": {},
"metadata": {},
"expires_at": 123,
"filename": "<string>"
}
'const options = {
method: 'PATCH',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({tags: {}, metadata: {}, expires_at: 123, filename: '<string>'})
};
fetch('https://{host}/v2/workspaces/slug:storage/webhooks/v1/knowledge_bases/{knowledgeBaseId}/documents/{documentId}', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));import requests
url = "https://{host}/v2/workspaces/slug:storage/webhooks/v1/knowledge_bases/{knowledgeBaseId}/documents/{documentId}"
payload = {
"tags": {},
"metadata": {},
"expires_at": 123,
"filename": "<string>"
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.patch(url, json=payload, headers=headers)
print(response.text){
"id": "vsf_550e8400-e29b-41d4-a716-446655440000",
"object": "knowledge_base.document",
"knowledge_base_id": "vs_7c9e6679-7425-40de-944b-e07fc1f90ae7",
"source_type": "connector_document",
"source_key": "web://https://contoso.sharepoint.com/sites/x/Shared%20Documents/report.pdf",
"source_url": "https://contoso.sharepoint.com/sites/x/Shared%20Documents/report.pdf",
"native_file_id": null,
"native_file_workspace_id": null,
"origin": "user",
"web_source_id": null,
"crawler_document_id": "crawl_doc_8842",
"status": "completed",
"index_generation": 3,
"filename": "report.pdf",
"mime_type": "application/pdf",
"bytes": 234567,
"parser": "tika",
"parsed_at": 1717000000,
"page_count": 12,
"char_count": 48213,
"chunking_strategy": null,
"scope": "knowledge",
"conversation_id": null,
"expires_at": null,
"tags": {
"project": "contracts-2026"
},
"metadata": {
"connector": "sharepoint",
"site_id": "site_123",
"drive_item_id": "item_456",
"version": "42"
},
"chunks_count": 37,
"vectors_count": 37,
"last_error": null,
"indexed_at": 1717000050,
"created_at": 1714972900,
"updated_at": 1717000050
}Update document metadata
Editable: tags, metadata, expires_at, filename.
source_url, source_key, native_file_id, and source_type
are immutable - re-keying a source means deleting and
re-attaching. To refresh fetch_url or re-trigger indexing,
use the POST upsert or /reindex. Requires editor+.
curl --request PATCH \
--url https://{host}/v2/workspaces/slug:storage/webhooks/v1/knowledge_bases/{knowledgeBaseId}/documents/{documentId} \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"tags": {},
"metadata": {},
"expires_at": 123,
"filename": "<string>"
}
'const options = {
method: 'PATCH',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({tags: {}, metadata: {}, expires_at: 123, filename: '<string>'})
};
fetch('https://{host}/v2/workspaces/slug:storage/webhooks/v1/knowledge_bases/{knowledgeBaseId}/documents/{documentId}', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));import requests
url = "https://{host}/v2/workspaces/slug:storage/webhooks/v1/knowledge_bases/{knowledgeBaseId}/documents/{documentId}"
payload = {
"tags": {},
"metadata": {},
"expires_at": 123,
"filename": "<string>"
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.patch(url, json=payload, headers=headers)
print(response.text){
"id": "vsf_550e8400-e29b-41d4-a716-446655440000",
"object": "knowledge_base.document",
"knowledge_base_id": "vs_7c9e6679-7425-40de-944b-e07fc1f90ae7",
"source_type": "connector_document",
"source_key": "web://https://contoso.sharepoint.com/sites/x/Shared%20Documents/report.pdf",
"source_url": "https://contoso.sharepoint.com/sites/x/Shared%20Documents/report.pdf",
"native_file_id": null,
"native_file_workspace_id": null,
"origin": "user",
"web_source_id": null,
"crawler_document_id": "crawl_doc_8842",
"status": "completed",
"index_generation": 3,
"filename": "report.pdf",
"mime_type": "application/pdf",
"bytes": 234567,
"parser": "tika",
"parsed_at": 1717000000,
"page_count": 12,
"char_count": 48213,
"chunking_strategy": null,
"scope": "knowledge",
"conversation_id": null,
"expires_at": null,
"tags": {
"project": "contracts-2026"
},
"metadata": {
"connector": "sharepoint",
"site_id": "site_123",
"drive_item_id": "item_456",
"version": "42"
},
"chunks_count": 37,
"vectors_count": 37,
"last_error": null,
"indexed_at": 1717000050,
"created_at": 1714972900,
"updated_at": 1717000050
}Authorizations
User session JWT or instance API key (iak_*). Send as Authorization: Bearer <token>.
Path Parameters
Knowledge base id. Legacy physical prefix vs_ (the kb_ rename is deferred).
128^vs_[A-Za-z0-9-]+$Document id. Legacy physical prefix vsf_ (the doc_ rename is deferred).
128^vsf_[A-Za-z0-9-]+$Body
Response
Updated document.
Association between a source and a knowledge base - the only
membership model (no files registry). The server computes
source_key and dedups on (knowledge_base_id, source_key).
fetch_url is intentionally ABSENT from this schema: it is
write-only at the API boundary (may embed credentials). For
source_type: uploaded_file no fetch URL is stored at all -
storage mints a fresh short-lived one (as a privileged
workspace) whenever the crawler needs bytes, so expired-token
failures are structurally impossible for uploaded files.
128^vsf_[A-Za-z0-9-]+$knowledge_base.document ^vs_[A-Za-z0-9-]+$Discriminator. uploaded_file for platform-native files
(attached by native_file_id); remote_file for document
bytes at an arbitrary URL; web_page for HTML pages
(single URL or crawl-discovered); connector_document for
sources owned by a third-party connector.
uploaded_file, remote_file, web_page, connector_document Server-computed canonical source URI; the dedup key,
UNIQUE with knowledge_base_id.
prisme-file://{workspace_id}/{native_file_id} for
uploaded files (stable across renames - never the rebuilt
native URL); web://{normalized_url} otherwise.
Normalization is conservative (strip fragment, lowercase
scheme + host, normalize percent-encoding, strip default
ports - query params untouched) and shared with the
crawler's canonicalization.
2048User-facing provenance URL - citations, UI links, audit
logs. Stable by construction for connector documents
(e.g. SharePoint webUrl) and web pages (the page URL). For
uploaded files, a display URL (caller-overridable at
attach time); downloadable links are minted lazily via
GET /documents/{document_id}/source_url.
Provenance, set at row creation and never overwritten by
seed adoption. Seed deletion cascades only over
origin: web_source rows - a manually attached page later
discovered by a seed keeps origin: user and survives the
seed's deletion (losing only its web_source_id).
user, web_source Authoritative indexing status. Transitions are guarded by
index_generation - stale or duplicate callbacks are
ignored. fetch_expired is connector-facing: the stored
ephemeral fetch_url no longer works and the owning
connector must refresh it via the upsert (POST /documents with the same source_url); it is never a
user-actionable error and never occurs for
uploaded_file sources. rejected means an external hook
(before_file_ingest / after_file_parse) blocked the
content - see rejection_reason / rejected_by.
queued, in_progress, completed, failed, fetch_expired, rejected Platform-native file id when source_type: uploaded_file.
Workspace owning the native file. Defaults to the caller's workspace.
Primary producing/adopting seed (origin-of-record), when
any. Multi-attribution (a page reachable from several
seeds) is carried by parent_web_source_ids.
^seed_[A-Za-z0-9-]+$All seeds whose crawl scope covers this page
(multi-attribution, §F-5). Backs per-seed page counts and
seed cascade-delete: deleting a seed removes it from this
array and drops the row only when the array empties AND
origin: web_source. Empty/absent ⇒ unattributed (counted
in the /web_sources summary residual).
^seed_[A-Za-z0-9-]+$Crawler-side document id, set once the crawler has seen this source.
Monotonically increasing per document; incremented on every (re)index. Search reads only the latest committed generation; a reindex swaps the new generation in only on success, so the previous good vectors remain searchable on failure.
x >= 1255x >= 0Parser used at last successful parse.
x >= 0x >= 0Per-document override of the store default.
knowledge, conversation Unix seconds. TTL for conversation-scope documents.
Caller-supplied tags. Editable via PATCH. Filterable on list.
Connector-supplied structured context (e.g. connector,
site_id, drive_item_id, version). Editable via PATCH.
x >= 0x >= 0Most recent failure context. Cleared when a new indexing
attempt transitions to in_progress. code: SOURCE_UNAVAILABLE signals a dangling reference (e.g. the
native file was deleted out-of-band - native files emit no
lifecycle events, so this surfaces at the next fetch).
Human-readable narrative status, distinct from last_error
(e.g. a partial-success or skipped note).
Unix seconds of the most recent failure.
Set when status: rejected. Why an external hook blocked
the content. Surfaced to the user only when the resolved
hook config sets expose_reason: true.
Identifier of the hook that produced the rejection.
Unix seconds. Set when the document reaches completed.
Was this page helpful?