Remove a document from the Knowledge Base

When a document is out of date or was uploaded by mistake, you can remove it yourself. Your Agent stops using it straight away.

It takes two calls: find the document's id, then remove it.

# 1. Find it (search by title, description or filename)
curl "https://mcp.onkey.chat/functions/v1/rest-api/documents?query=spring%20menu" \
  -H "Authorization: Bearer okm_<your-token-here>"
# → { "documents": [ { "id": "7c2e4b1a-...", "filename": "spring-menu.pdf", "status": "ready", ... } ], ... }

# 2. Remove it
curl -X DELETE "https://mcp.onkey.chat/functions/v1/rest-api/documents/7c2e4b1a-9d3f-4e6a-8b5c-1f2a3b4c5d6e" \
  -H "Authorization: Bearer okm_<your-token-here>"
# → { "id": "7c2e4b1a-...", "filename": "spring-menu.pdf", "status": "deleted" }

Already have the id from an upload?

When you upload documents, the batch status gives each file a document_id once it has been picked up for processing. Keep it, and you can remove exactly that file later without searching:

{ "files": [ { "document_id": "7c2e4b1a-...", "filename": "spring-menu.pdf", "status": "done", "error": null } ] }

Listing documents

GET /documents returns your documents newest first, 50 per page. Pass page=2 and so on for the rest, and status=ready (or any other status) to narrow the list. Removed documents are not listed.

What removal does

Your Agent stops using the document straight away.
It's removed the same way as on the Knowledge Base Manager page, with the same safety checks. A document the page wouldn't remove is refused here too, and nothing is removed.
Mistakes can be undone for 30 days. We keep a copy for 30 days and then erase it for good. To get a document back within that time, ask our team (see Getting help).
It's safe to retry. Removing a document that's already gone returns 404 not_found.

When a removal is refused

Status	`error`	What to do
`409`	`document_processing`	The document is still being added. Try again once it's finished.
`409`	`review_pending`	It's part of an open duplicate or contradiction review. Resolve the review first.
`409`	`replacement_in_progress`	A replacement for it is still being processed. Try again shortly.
`409`	`needs_support`	It couldn't be removed safely. Ask our team to remove it (see Getting help).
`502`	`delete_failed`	It didn't complete this time. Retry: it's safe, and a retry finishes a removal that was interrupted.

For the full request and response schema, see the API Reference.

Next steps

Upload documents — add the up-to-date version.
Errors — the error format and every status code.