Skip to main content
DELETE
Remove a knowledge source
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/synchronized-sources/remove with { sourceId, reason } removes one source in the caller’s writable namespaces, as Remove does on the Console Knowledge › Synchronized sources page. It needs knowledge:manage and answers 200 with { sourceId, namespace, purgeScheduled }. MCP hosts call it through forge_call_operation with operationId removeSynchronizedSource.
Removal permanently deletes every case the source wrote, then its runs and the source. It cannot be undone.
reason is 1–500 characters, stored redacted on the audit event, and the removal is audited as the credential. A sync source is paused at once, its open run is closed, and the purge is scheduled (purgeScheduled: true). An unowned retired connection is deleted at once (purgeScheduled: false). Removing a source already being removed restarts its purge and records no second audit event. Send an Idempotency-Key to retry safely: a repeat removes nothing again. It returns the recorded 200 only while the credential still holds knowledge:read and the namespace the response names is still writable. The namespace, not the source, is rechecked, so a completed removal stays disclosable after its purge. Otherwise it answers 403 for a missing knowledge:read, or 409 idempotency_result_unavailable. See Knowledge source replay.

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

synchronizedSourceId
string
required
Minimum string length: 1

Body

application/json

The source to remove, and why (1 to 500 characters, stored redacted).

reason
string
required
Required string length: 1 - 500

Response

The removal's outcome

data
object
required

A removal's outcome. purgeScheduled: true: the source is paused and the purge that deletes every case it wrote, its runs and the source is scheduled. purgeScheduled: false: an unowned retired connection was deleted at once.

meta
object
required