Delete a knowledge base
Permanently delete a knowledge base and everything indexed in it.
Permanently delete a knowledge base and everything indexed in it.
THIS IS IRREVERSIBLE and there is no undo: the vectors are removed from the search index and the upload records are deleted. Re-adding the content means re-uploading and re-indexing it.
Agents configured to search this collection will stop finding anything in it. They are NOT reconfigured for you — an agent still naming a deleted collection simply retrieves nothing, which is visible in its transcripts rather than as an error at delete time.
If a delete fails part-way, the knowledge base stays listed and the delete can be
retried — a listing never says the text is gone while /query can still return
it.
A knowledge base belonging to another organisation answers 404, exactly as a name that does not exist does.
Rate limit: 2000 requests per minute per organization, counted together with every endpoint that has no stricter limit of its own. Exceeding it returns 429 with Retry-After; the X-RateLimit-* response headers report your remaining allowance on every call.
v2/knowledge-bases/{collection}Authorization
AuthorizationRequiredBearer <token>
Your Graine API key. Create one in the dashboard under Developers, or via POST /v2/api-keys. Send it as Authorization: Bearer <key>.
In: header
Path Parameters
collectionRequiredCollection
The knowledge base to delete.
Query Parameters
organization_idOrganization Id
Must match the organisation the API key belongs to.
Response Body
200
Confirmation, with the number of indexed chunks removed.
deletedRequiredDeleted
True when the resource existed and has been removed.
collectionCollection | null
The knowledge base the deletion applied to.
record_idRecord Id | null
The upload that was removed, for a document deletion.
uploads_removedUploads Removed | null
Upload records removed. Only set for a knowledge-base deletion.
vectors_removedVectors Removed
Indexed chunks removed from the search index. This is the number that matters for a deletion request: once it is zero-from-nonzero, the text is no longer retrievable by a query.
0400
1000 — malformed input (bad knowledge base name, unreadable or empty file).
errorRequiredError
Stable integer code from the /v2 error table. Branch on this.
messageRequiredMessage
One human-readable sentence. Wording may change; the code will not.
401
1100 — missing, unknown or inactive API key. 1101 — a browser session token was presented.
errorRequiredError
Stable integer code from the /v2 error table. Branch on this.
messageRequiredMessage
One human-readable sentence. Wording may change; the code will not.
403
1102 — the key is valid but lacks the scope this endpoint requires, or names another organisation. GET /v2/scopes reports which scopes the key holds.
errorRequiredError
Stable integer code from the /v2 error table. Branch on this.
messageRequiredMessage
One human-readable sentence. Wording may change; the code will not.
404
1200 — no such knowledge base in this organisation. Cross-tenant reads answer 404, never 403.
errorRequiredError
Stable integer code from the /v2 error table. Branch on this.
messageRequiredMessage
One human-readable sentence. Wording may change; the code will not.
422
1001 — the body or query failed validation; the message names the first offending field.
errorRequiredinteger
Stable integer code from the error table. Branch on this, not on the message.
messageRequiredstring
One human-readable sentence. Wording may change; the code will not.
429
1300 — per-organisation rate limit exceeded. Carries Retry-After.
errorRequiredError
Stable integer code from the /v2 error table. Branch on this.
messageRequiredMessage
One human-readable sentence. Wording may change; the code will not.
503
1501 — knowledge bases are temporarily unavailable; retry.
errorRequiredError
Stable integer code from the /v2 error table. Branch on this.
messageRequiredMessage
One human-readable sentence. Wording may change; the code will not.
504
1502 — the request did not finish in time. A slow upload may still finish indexing.
errorRequiredError
Stable integer code from the /v2 error table. Branch on this.
messageRequiredMessage
One human-readable sentence. Wording may change; the code will not.
Confirmation, with the number of indexed chunks removed.