Working with Knowledge

Knowledge bases and versions

All knowledge in Maven starts with a Knowledge Base, a container for documents that allows for group operations. Users can set the refresh frequency for Knowledge Bases and deactivate an entire Knowledge Base to remove it from their Agent.

Knowledge Bases have versions. Every time a Knowledge Base is refreshed, a new version must be created. This allows the current version of knowledge to be served while the new version is still processing. When all Knowledge Documents have been created, the version must then be finalized. Versions can be finalized in a success or failure state, allowing errors to be surfaced to the user. Users can view version history within the Maven dashboard and can require versions to be manually reviewed before they become active.

API callers do not control the refresh frequency, active status, or current version of Knowledge Bases.

Knowledge documents

Within a Knowledge Base, there are multiple documents. Each document should focus on a single topic to optimize search results. Documents that are too large will be split into multiple pieces.

Document content is stored in Markdown, but the API allows HTML during creation, which is automatically converted into Markdown.

Like Knowledge Bases, individual knowledge documents can also be deactivated. API callers do not control the active status of individual documents.

Creating Knowledge with a Serverless Maven App

Maven Apps that create knowledge typically fall into two categories: those with external APIs that provide webhook support and those without.

For both types of API callers, it is recommended to implement both preInstall and postInstall methods within your typescript interface.


In preInstall, typically the authentication of the external API is checked. This API should return quickly and surface any validation errors to the user.


In postInstall, Knowledge Bases should be created along with a full set of documents. The steps are as follows:

  • Create a Knowledge Base.
  • Create a Knowledge Base Version of type full.
  • Create as many Knowledge Documents as needed.
  • Finalize the Knowledge Base Version.

Refreshing Knowledge Bases

Additionally, the app should implement the refreshKnowledgeBase method. This method is triggered when the user manually requests a refresh or when the Knowledge Base is being refreshed automatically by the Maven platform. The ID of the Knowledge Base being refreshed will be passed into this method. Using the same logic as in postInstall, a new Knowledge Base version should be created, populated with documents, and then finalized.

Note that updateDocument and deleteDocument are not valid API calls within a Knowledge Base Version of type full.

Partial Knowledge Base Updates

If the external API you are working with supports webhooks, you can also provide partial version updates. Within this type of Knowledge Base version, the API caller can use the createDocument, updateDocument, and deleteDocument methods to provide incremental changes of the Knowledge Base. When the Knowledge Base is finalized, the platform will merge these incremental changes with the latest version to determine the final state of the documents within the version.

Example Maven Apps

Was this page helpful?