Skip to main content
DELETE
Delete a knowledge entry
The reference panel describes the current v3 operation. The notes below describe its v2 compatibility API. Follow the v3 request schema for current calls: v3 can move identifiers from the body or query into the URL. Keep the v2 method, path, and payload together when using the compatibility API.

v2 compatibility notes

POST /api/v2/knowledge/delete removes the entry’s indexed content, leaves a tombstone and answers 200 with { "id", "status": "deleted", "alreadyDeleted" }:
  • alreadyDeleted: false — this call deleted the entry and wrote its audit event, recorded with the credential’s attribution: a Personal key as its owner, with the key named on the audit event (via: "personal_key", apiKeyId); an External App as external-app:<id>, with the people who granted its access; a platform key as platform-key:<id>.
  • alreadyDeleted: true — the entry was already deleted; nothing was written.
The decision is made inside the delete’s own transaction, so of two racing deletes of one entry exactly one answers alreadyDeleted: false. Send an Idempotency-Key header to make a retry return the original answer; see Knowledge write replay.

Errors

No such entry, or it is outside the caller’s writable namespaces.
The entry is a case synced from a knowledge source; the next sync would write it again. Remove it at the source, or remove the source.

Authorizations

Authorization
string
header
required

An External App: the JWT it obtains from POST /oauth/token with OAuth2 client_credentials. Pass as Authorization: Bearer <jwt>. An app's static companion key also authenticates as the app, but is deprecated and is not protected by Idempotency-Key.

Headers

Idempotency-Key
string

1–255 printable ASCII characters. A repeat with the same key and request never runs the write again, a 5xx included. It returns the first response (Idempotency-Replayed: true) only when the route's current authorization policy permits disclosure; otherwise 409 idempotency_result_unavailable. Honoured for External App JWTs and platform and MCP keys; an External App's static companion key is not protected.

Required string length: 1 - 255

Path Parameters

entryId
string
required

Knowledge entry id (the id returned by getChunks or addKnowledge).

Body

application/json
reason
string

Why the entry is deleted; recorded on the audit event.

Maximum string length: 500

Response

Knowledge entry deleted by this call (alreadyDeleted: false) or before it (alreadyDeleted: true)

data
object
required

A knowledge delete's outcome. alreadyDeleted is false only for the call that deleted the entry (and wrote its audit event); a repeat, or the loser of two racing deletes, answers true.

meta
object
required