Delete one uploaded document
Permanently delete one uploaded document and every chunk it produced.
Permanently delete one uploaded document and every chunk it produced.
THIS IS IRREVERSIBLE. Use it when the wrong file was uploaded, or when a document must be removed to satisfy a deletion request: after this returns, the text is no longer retrievable by any query against this knowledge base.
vectors_removed is the number that matters — it counts indexed chunks, not files.
One PDF commonly becomes hundreds.
An id belonging to another organisation answers 404, identically to one that does not exist. The knowledge base itself is left in place even when its last document is removed; delete the knowledge base to remove that too.
Rate limit: 1000 requests per minute per organization (bucket default). Exceeding it returns 429 with Retry-After; the X-RateLimit-* response headers report your remaining allowance on every call.
v2/knowledge-bases/{collection}/documents/{document_id}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 the upload belongs to.
document_idRequiredDocument Id
The upload's id, as returned by GET /v2/knowledge-bases/{collection}/documents. This identifies one UPLOAD, which may have produced many indexed chunks — all of them are removed.
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 — the knowledge service is unreachable or returned a 5xx.
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 knowledge service did not respond in time. A slow ingest may still complete.
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.