Force a re-run of the indexing pipeline (re-fetch, re-parse, re-chunk, re-embed)

Forced FULL re-run of the pipeline - fetch, parse, chunk, embed, vector swap - on an EXISTING document only. 404 when the document does not exist; no create or upsert semantics. Increments index_generation; the previous good vectors remain searchable until the new generation commits.

This is also the rechunk operation: pass chunking_strategy to re-run with new settings. The override is persisted on the document (replacing any previous per-document override) so later re-runs reuse it. Pass the reserved value {"type": "default"} to clear the override so the document follows its knowledge base again; this is the only route that accepts it. Documents without an override pick up the store-level chunking_strategy on their next run; to re-run a whole store use POST /v1/knowledge_bases/{knowledgeBaseId}/reindex.

For a web_page document this also re-fetches its URL through the crawler (a single-page refresh).

Fetch behaviour by source type:

• uploaded_file - storage mints a fresh native fetch URL; cannot expire.
• web_page / remote_file - the crawler re-fetches the URL.
• connector_document - its content was fetched through the connector with a short-lived signed URL that is never stored, so storage cannot fetch it again itself. The parser / chunking_strategy override is saved first, then storage asks the document’s connection for a targeted resynchronization of this one document (no listing of the source, no failure backoff). The response is 202 with the document unchanged and a resync object; the document switches to in_progress within seconds, when the connection re-sends it, and is indexed with the saved override - now and at every later synchronization. Only the connection’s owner can trigger it (409 CONNECTOR_RESYNC_OWNER_ONLY otherwise; the override stays saved and applies at the next synchronization). While the connection synchronizes, the resynchronization is queued behind it (resync.queued: true) rather than refused. A connector document materialized as a native file is re-fetched like an uploaded_file while that copy exists; once it has expired, the document is delegated to its connection as above.

Requires editor+.

POST /v1/knowledge_bases/{knowledgeBaseId}/documents/{documentId}/reindex

Force a re-run of the indexing pipeline (re-fetch, re-parse, re-chunk, re-embed)

cURL

curl --request POST \
  --url https://{host}/v2/workspaces/slug:storage/webhooks/v1/knowledge_bases/{knowledgeBaseId}/documents/{documentId}/reindex \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "chunking_strategy": {},
  "parser": "<string>",
  "reason": "<string>"
}
'

202

Example

{
  "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

BearerAuthWorkspaceApiKeyAuth

Authorization · string · header · required

User session JWT or instance API key (iak_*). Send as Authorization: Bearer <token>.

Path Parameters

knowledgeBaseId · string · required

Knowledge base id. Legacy physical prefix vs_ (the kb_ rename is deferred).

Maximum string length: 128

Pattern: ^vs_[A-Za-z0-9-]+$

documentId · string · required

Document id. Legacy physical prefix vsf_ (the doc_ rename is deferred).

Maximum string length: 128

Pattern: ^vsf_[A-Za-z0-9-]+$

Body

application/json

chunking_strategy · object

Rechunk with these settings. Persisted as the document's chunking_strategy override. The reserved value {"type": "default"} clears that override, so the document follows its knowledge base again. This is the only route that accepts it; the others reject it with VALIDATION_ERROR.

parser · string

Per-document parser override, persisted on the document and reused by later re-runs. The sentinel value "default" clears any existing override (reverts to the store-level parser).

reason · string

Free-form audit context (e.g. parser_upgrade).

Maximum string length: 256

Response

202

application/json

Re-indexing queued; document returned with status: in_progress. For a connector document, the document is returned as it was, with resync: {connection_id, sync_id, queued}: its connection re-sends it and it switches to in_progress within seconds, or once the running synchronization ends when queued is true.

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.

id · string · required

Maximum string length: 128

Pattern: ^vsf_[A-Za-z0-9-]+$

object · enum<string> · required

Available options: knowledge_base.document

knowledge_base_id · string · required

Pattern: ^vs_[A-Za-z0-9-]+$

source_type · enum<string> · required

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.

Available options: uploaded_file, remote_file, web_page, connector_document

source_key · string · required · read-only

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.

Maximum string length: 2048

source_url · string<uri> · required

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

origin · enum<string> · required

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

Available options: user, web_source

status · enum<string> · required

Authoritative indexing status. Transitions are guarded by index_generation - stale or duplicate callbacks are ignored. fetch_expired is connector-facing: the 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 a before_file_ingest hook blocked the content (an after_file_parse block is failed with last_error.code: HookRejected) - see rejected_by, and public_rejection_reason for the only reason that may be shown to an end user.

Available options: queued, in_progress, completed, failed, fetch_expired, rejected

created_at · integer · required

native_file_id · string | null

Platform-native file id when source_type: uploaded_file.

native_file_workspace_id · string | null

Workspace owning the native file. Defaults to the caller's workspace.

web_source_id · string | null

Primary producing/adopting seed (origin-of-record), when any. Multi-attribution (a page reachable from several seeds) is carried by parent_web_source_ids.

Pattern: ^seed_[A-Za-z0-9-]+$

parent_web_source_ids · string[] · read-only

All seeds whose crawl scope covers this page. 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).

Pattern: ^seed_[A-Za-z0-9-]+$

crawler_document_id · string | null

Crawler-side document id, set once the crawler has seen this source.

index_generation · integer · read-only

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.

Required range: x >= 1

filename · string | null

Maximum string length: 255

mime_type · string | null

bytes · integer | null

Required range: x >= 0

parser · string | null

Parser used at last successful parse.

parsed_at · integer | null

page_count · integer | null

Required range: x >= 0

char_count · integer | null

Required range: x >= 0

chunking_strategy · object | null

Per-document override of the store default.

scope · enum<string> · default: knowledge

Available options: knowledge, conversation

conversation_id · string | null

expires_at · integer | null

Unix seconds. TTL for conversation-scope documents.

tags · object

Caller-supplied tags. Editable via PATCH. Filterable on list.

metadata · object

Connector-supplied structured context (e.g. connector, site_id, drive_item_id, version). Editable via PATCH.

chunks_count · integer | null

Required range: x >= 0

vectors_count · integer | null

Required range: x >= 0

last_error · object | null

Most 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).

Hide child attributes

last_error. code · string

last_error. message · string

last_error. details · object

last_error. timestamp · integer

errors · object[] | null · read-only

Bounded retry/failure history (the most recent failure is also in last_error). For debugging repeated index failures.

Hide child attributes

errors. code · string

errors. message · string

errors. timestamp · integer

message · string | null

Human-readable narrative status, distinct from last_error (e.g. a partial-success or skipped note).

failed_at · integer | null

Unix seconds of the most recent failure.

rejection_reason · string | null

Why an external hook blocked the content, as the hook gave it, kept whether or not the hook config sets expose_reason, so it is for the knowledge base's administrators: never relay it to an end user, and returned only to the base's owners and storage / platform admins (null for any other reader). Set when status: rejected (before_file_ingest) and on a document failed with last_error.code: HookRejected (after_file_parse). With public_rejection_reason and rejected_by, it is the trace of the last refusal: a reindex keeps it and the next failure resets it, so it is meaningful only while the document is rejected or failed with last_error.code: HookRejected.

public_rejection_reason · string | null

The part of rejection_reason the hook allowed to be shown (expose_reason: true); empty otherwise. The only refusal reason a client or an agent may relay to the end user.

rejected_by · string | null

Identifier of the hook that produced the rejection.

indexed_at · integer | null

Unix seconds. Set when the document reaches completed.

updated_at · integer

resync · object

Present only for a connector document - the targeted resynchronization requested from its connection.

Hide child attributes

resync. connection_id · string

resync. sync_id · string

resync. queued · boolean

The connection was synchronizing; the resynchronization waits for it to end.