Purge a Document from every version

POST /v1/knowledge-bases/{knowledge_base_id}/documents/{document_id}/purge

Property	Value
Operation	`purge_knowledge_document`
Group	Knowledge bases
Scope	`knowledge:write`
Route class	`control`
Idempotency	`Idempotency-Key` accepted: a retry with the same key replays the first answer
Audit	Audited `knowledge.document.purge` (mutation)
Released in	1.53.0
Phase 0 host	Served (the hosted api pins 1.65.0)

Removes the Chunks and vectors of every revision of the Document from every version at once, and its stored file, at the revision If-Match names (1.53.0; knowledge-bases.md section 9), for content that must not be served or kept; the affected versions keep working without it. Answers the Document removed with purged_at; a purged Document answers unchanged. The one operation that overrides the immutability of versions, accepted on an archived Knowledge base too.

Request

Set VOCAL_API to the base URL of your API and VOCAL_API_KEY to an API key with the knowledge:write scope (Authentication and keys). Replace each placeholder, such as agt_... or <name>, with your own value.

curl -X POST "$VOCAL_API/v1/knowledge-bases/kb_.../documents/kdoc_.../purge" \
  -H "Authorization: Bearer $VOCAL_API_KEY" \
  -H 'If-Match: "1"' \
  -H "Idempotency-Key: $(uuidgen)"

const response = await fetch(`${process.env.VOCAL_API}/v1/knowledge-bases/kb_.../documents/kdoc_.../purge`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.VOCAL_API_KEY}`,
    'If-Match': '"1"',
    'Idempotency-Key': crypto.randomUUID(),
  },
});
console.log(response.status, await response.text());

import os
import uuid

import requests

response = requests.post(
    f"{os.environ['VOCAL_API']}/v1/knowledge-bases/kb_.../documents/kdoc_.../purge",
    headers={
        "Authorization": f"Bearer {os.environ['VOCAL_API_KEY']}",
        "If-Match": '"1"',
        "Idempotency-Key": str(uuid.uuid4()),
    },
)
print(response.status_code, response.text)

Parameters

Name	In	Type	Required	Description
`knowledge_base_id`	path	KnowledgeBaseId	yes	The id of a Knowledge base: `kb_` and the row's UUIDv7 in 26 Crockford base32 characters. Opaque and safe to log.
`document_id`	path	KnowledgeDocumentId	yes	The id of a Document of a Knowledge base: `kdoc_` and the row's UUIDv7 in 26 Crockford base32 characters. Opaque and safe to log.
`if-match`	header	string	yes	The revision the change was made against, quoted as the ETag returns it, or `*` to overwrite.
`idempotency-key`	header	string	no	A client-chosen key, kept 24 hours per Organization, environment and route. A replay returns the stored response.

Responses

Status	Content type	Shape	Error codes
`200`	`application/json`	KnowledgeDocument
`400`	`application/json`	ErrorEnvelope	`invalid_request`
`401`	`application/json`	ErrorEnvelope	`unauthenticated`
`403`	`application/json`	ErrorEnvelope	`forbidden`, `org_suspended`
`404`	`application/json`	ErrorEnvelope	`not_found`
`409`	`application/json`	ErrorEnvelope	`idempotency_in_progress`, `idempotency_key_reused`
`412`	`application/json`	ErrorEnvelope	`revision_mismatch`
`428`	`application/json`	ErrorEnvelope	`precondition_required`
`429`	`application/json`	ErrorEnvelope	`rate_limited`
`500`	`application/json`	ErrorEnvelope	`internal_error`

Fields of the `200` answer

The shape is KnowledgeDocument.

Field	Type	Required	Description
`byte_size`	integer or null	yes
`chunk_count`	integer	yes
`chunker_version`	string or null	yes
`classification`	KnowledgeClassification or null	yes
`created_at`	Timestamp	yes
`embedding_space`	EmbeddingSpace or null	yes
`entity_counts`	array of KnowledgeEntityCount	yes
`error_code`	IngestionErrorCode or null	yes	Set when `failed`.
`external_ref`	string or null	yes	The file name, URL or vendor reference the Source knows the Document by. The content class `names`: null unless the read names `include=names`, and null in the answer of a write (1.53.0, second part).
`id`	KnowledgeDocumentId	yes
`indexed_at`	Timestamp or null	yes
`knowledge_base_id`	KnowledgeBaseId	yes
`last_ingestion_run_id`	IngestionRunId or null	yes
`media_type`	KnowledgeMediaType or null	yes
`object`	`"knowledge_document"`	yes
`page_count`	integer or null	yes
`parser_version`	string or null	yes
`purged_at`	Timestamp or null	yes
`quarantine_expires_at`	Timestamp or null	yes	When the parsed text held for review is deleted, 14 days after the quarantine (a target); null otherwise.
`quarantined_at`	Timestamp or null	yes
`review_status`	KnowledgeReviewStatus	yes
`revision`	integer	yes	Counts writes to the Document; returned as the ETag and required in If-Match. Not the number of content revisions.
`source_id`	KnowledgeSourceId	yes
`status`	KnowledgeDocumentStatus	yes
`tags`	array of DocumentTag	yes
`title`	string or null	yes	The title the upload or the parse stage gave, or null when it has none. The content class `names`: null unless the read names `include=names`, and null in the answer of a write (1.53.0, second part).
`updated_at`	Timestamp	yes

Purge a Document from every version

Request

Parameters

Responses

Fields of the 200 answer

Fields of the `200` answer