Deprecate, Replace, or Delete a Knowledge-Base Document

Removing an outdated document from an AI knowledge base means taking it out of search, not labeling it old. In Insulin, an uploaded file can be deprecated, replaced or deleted, and each treats answers and re-embedding differently; a crawled page or a synced document can’t be deprecated, so it is fixed at its source.

---

An agent keeps quoting last year’s refund policy. This year’s is in the knowledge base too, and the old file still wins often enough to matter. The reflex is to delete it, and sometimes that is right. But Insulin gives you three ways to deal with a document: Deprecate it, replace it with a same-name upload, or Delete it. They differ in what they do to answers, to the document itself, and to the knowledge base’s next embedding-model change, and which of them you have depends on where the document came from.

This post is the decision. If your problem is the opposite one, a document the agent can’t find, start with why an AI knowledge base isn’t finding documents, which covers a Deprecated status and how to undo it.

How do you remove an outdated document from an AI knowledge base?

Take it out of search, and pick the action by where the document came from. For an uploaded or pasted file, deprecate it if you may need it again, replace it if a new version exists, and delete it only if it should never have been there. A crawled web page or a synced document can’t be deprecated, so fix it at its source and sync again.

Deprecating is retiring an indexed file from search without deleting it: its document and chunks stay intact, and Restore brings it back into search with no re-upload.

A note reading “superseded” at the top of the old file doesn’t do the same job. Insulin splits every document into chunks, and an agent answers from the passages it retrieves, so the note travels only with the passage it sits in.

Which actions work on a file, a website or a connector?

All three work on an uploaded or pasted file; a website or connector document can’t be deprecated, so you change it at its source or remove it with its website or connector. Find the row for where the outdated document came from:

Source	Deprecate	Replace	Delete
Uploaded or pasted file	Yes, once it reads Indexed: it leaves search and can be restored	Upload the new version under the same name	Delete the file
Crawled website	Not available	Update the page on the site, then Re-sync the website	Remove the website
Connector (Google Drive, GitHub, ClickUp)	Not available	Update the item at its source, then Re-sync	Remove it at its source, narrow the connector with Edit scope, or Remove the connector

Uploaded and pasted files

Replace when a new version exists, deprecate when nothing replaces the file or you may want it back, and delete only what should never have been added.

• Replace. Uploading a file with the same name replaces the existing document in place, and like any upload it answers once it reads Indexed. A revision uploaded under another name, say refund-policy-2026.pdf beside refund-policy-2025.pdf, is a second document, and both keep answering until you deprecate the old one.
• Deprecate. Use it for a file that is superseded with no successor, or one you may need again: last year’s policy that an audit could ask about, or a seasonal offer that will return. Deprecate is offered only once a file has finished indexing.
• Delete. Use it for the wrong upload, a duplicate, or content that must not be kept at all. Deprecating keeps the document and its chunks, which makes it the wrong tool when the problem is that the content is stored.

Crawled websites

A crawled website is a copy of the site as it stood when it was last crawled, so fix the page on the site. Update the page where it is published, then Re-sync the website: websites re-crawl only when you trigger it, never on their own. The row’s Last Sync column shows when the knowledge base last read the site.

If the site no longer belongs in the knowledge base, Remove it on the Websites tab. If one page is wrong and you can’t change it, crawl less of the site: remove it, then add back each page you still want as its own URL at a Depth of 1, which crawls the start page alone. Bulk add takes a spreadsheet of them; give it a depth column set to 1, because depth otherwise defaults to 3, and start a sync afterwards, because imported websites are added but not crawled.

Connectors

A connector keeps the knowledge base in sync with its source, so change the source. Update or remove the outdated item in Google Drive, GitHub or ClickUp, then Re-sync the connector to pick up the change now. With Auto-sync on, Insulin’s hourly sweep gets there on its own, running a full reconcile once the last one is more than 24 hours old; without Auto-sync, nothing changes until you re-sync.

When a whole folder, repository or space no longer belongs, narrow the connector with Edit scope. When the source no longer belongs at all, Remove the connector.

What does each action do to answers, search and re-embedding?

Deprecate hides a file and keeps it, Replace swaps its content in place, and Delete removes it. The differences that matter most show up later: at the next embedding-model change, and on the day you want something back.

Action	Answers and search	The document	At an embedding-model change	Getting it back
Deprecate	Out of search results, so no agent retrieves it	Kept, chunks and all	Skipped	Restore: it re-indexes, returns as Pending, then answers again
Replace, by uploading under the same name	The new version answers once it reads Indexed	Replaced in place	Re-embedded with the rest	Upload the earlier version under the same name
Delete	Out of search	Removed from the knowledge base	Nothing left to re-embed	No Restore: upload it again

Deprecating is a decision that nothing in the background undoes. A sync skips a document you deprecated rather than re-indexing it, and an embedding-model change passes over it, so Restore is the only way back into search. In the documentation’s words, “a sweep that quietly undid it every hour would make the control useless.”

Restore re-indexes, and that is deliberate. A deprecated file sits out every embedding-model change, so its stored embeddings may come from a model the knowledge base has since moved off, and putting them straight back into search would return poor matches rather than an error. A restored file comes back as Pending and answers again once indexing finishes, usually in about the time it took the first time, with nothing for you to do.

Retiring a whole knowledge base is a different action again. Delete Knowledge Base, in the Danger Zone at the bottom of its Settings, removes the knowledge base with all of its documents, chunks and embeddings, and cannot be undone.

Can an agent retire a document for you?

Yes, if the knowledge base is attached to it in Edit mode: an agent can then create, update and deprecate files, but never delete them. In Read mode it can only search and retrieve. Of the three actions, then, an agent can update a file or deprecate one, and deleting stays with people.

Edit also lets an agent rewrite what a file says, so keep it for agents whose job is maintaining that knowledge base; which agents can see which documents covers Read and Edit attachment. When you pick the built-in Insulin assistant’s knowledge bases yourself, each one carries a Read or Edit mode too, and Edit there only expresses intent: Fours re-checks your own role on that knowledge base immediately before every write.

How do you confirm the old version is gone?

Run Test search with the question that surfaced the old answer. Test search previews what an agent would retrieve, with each passage’s source document, so a retired file should no longer appear among the results. After a replacement or a re-sync, wait until the document reads Indexed before you test.

Frequently asked questions

What is the difference between deprecating and deleting a knowledge-base document?

Deprecating takes an indexed file out of search but keeps the document and its chunks, so Restore can bring it back. Deleting removes the document from the knowledge base, and only a deprecated file has a Restore.

Should I deprecate or delete an outdated policy document?

Deprecate it if it is an uploaded file: it leaves search and stays restorable, which matters if anyone may need it later. Delete only a file that should never have been added, or content that must not be kept at all.

Can I deprecate a crawled web page or a Google Drive document?

No. Only uploaded or pasted files can be deprecated; website and connector documents cannot. Update or remove it at its source and re-sync, narrow a connector with Edit scope, or remove the website or connector.

Will a sync bring a deprecated document back?

No. A sync skips a document you deprecated, and an embedding-model change passes over it too. Restore is the only way back into search, and it re-indexes the file, which returns as Pending before it answers again.

How do I replace an outdated file with a new version?

Upload the new version under the same name. It replaces the existing document in place and answers once it reads Indexed. Uploaded under a different name, it becomes a second document, so deprecate the old one.

Can an AI agent delete documents from a knowledge base?

No. An agent attached to a knowledge base in Edit mode can create, update and deprecate files, but never delete them. In Read mode it can only search and retrieve.

Takeaways

• Take an outdated document out of search. A “superseded” note inside it travels only with the passage it sits in.
• Only uploaded and pasted files can be deprecated. Deprecate keeps the file and its chunks, and only Restore brings it back, re-indexed.
• Replace a file by uploading its new version under the same name; a different name adds a second document.
• Delete what should never have been added. Deprecating keeps content; deleting removes it.
• Fix crawled pages and connector documents at the source and re-sync, or narrow the connector with Edit scope.
• An agent in Edit mode can create, update and deprecate files, never delete them.

A knowledge base earns trust by answering from what is current. See what Insulin knowledge bases do for a team, and keep the documentation on retiring a document to hand for the exact behavior.