Skip to main content
Base URL: https://convex.memorycrystal.ai. All routes below require Bearer authentication. {id} is a KB ID returned by the service.

​
Routes

​
List and create

List rows use _id, isActive, memoryCount, totalChars, createdAt, and updatedAt, plus name and available access/source metadata. They do not use id, status, or chunkCount aliases. scope supplies channel context to listing and identity resolution; it is not an exact KB scope filter. Scoped lists enforce visibility. Fully unscoped listing is an owner management inventory.
Creation returns only the ID envelope, not the full KB object. For MCP callers, use create and access tools.

​
Settings and access

PATCH accepts name, description, agentIds, scope, sourceType, sourceRole, isActive, and peerScopePolicy (strict or permissive). Set agentIds: [] to close access, a nonempty array to restrict it, or agentIds: null to explicitly open it.
The response’s access mode is open, closed, or restricted. KB row visibility depends on activity and agent allow-lists. Channel-bearing chunks have additional visibility checks; channel-less chunks are shared within a visible base. Separate accounts, not agent/channel settings, provide separate security boundaries.

​
Import and enumerate

Each chunk requires content. Metadata is optional and can contain title, sourceUrl, chunkIndex, totalChunks, and sourceType. A stable dedupeKey replaces an existing chunk in that KB. Keyless chunks append. The standard import loop awaits embedding and salience per chunk; an exception can stop the request after earlier chunks were saved. The result contains knowledgeBaseId, importedCount, updatedCount, memoryIds, memoryCount, and totalChars. For enumeration, call /api/knowledge-bases/{id}/memories?limit=100. The current HTTP handler converts an omitted limit to zero and clamps it to 1; explicitly supplying 100 avoids this. Maximum limit is 200. Pass continueCursor as the next cursor until isDone is true.

​
Query

Default limit is 8, maximum 20. The handler forwards query, limit, agentId, and channel; it does not forward threshold. Normal results contain knowledgeBase, memories, retrieval, and optional degradation. Visibility denial can instead return the KB with an empty memories array without diagnostics. Pass an explicit identity. Direct KB queries have limited identity inference; it does not guarantee visibility in every context. Empty results can reflect visibility, bounded candidates, or degradation. Use enumeration for a complete owner inventory, not a relevance query. MCP selection uses knowledgeBaseId or knowledgeBaseName, never kb_id.

​
Empty, archive, restore, delete

Empty deletes chunks and keeps the base ID/settings. It returns knowledgeBaseId, deletedMemories, activeDeletedMemories, and kept: true. The compatibility DELETE route archives a bounded set of up to 10,000 chunks and deactivates the KB; it does not permanently erase the KB. Use lifecycle jobs for large archive/delete operations. PATCH isActive: true reactivates the row but does not restore archived chunks automatically. A lifecycle delete is permanent; it is distinct from archive and empty. Obtain explicit approval before destructive operations. Embedding maintenance is available through POST /api/knowledge-bases/{id}/backfill with {"type":"embeddings"} and GET /api/knowledge-bases/{id}/backfill-status, which returns total/unembedded counts. This is separate from importing new content. See rate limits for key quotas and the additional account envelope on KB queries.

​
Request and response examples

These are raw HTTP bodies. Replace IDs and identity placeholders with your own values.

​
POST /api/knowledge-bases

Request body:
HTTP 201 response:

​
POST /api/knowledge-bases//import

Request body:
HTTP 201 response:

​
POST /api/knowledge-bases//query

Request body:
HTTP response (selected fields):

​
Import, verify, and refresh

Create the base, PATCH its intended access settings, and import the sections. List with the intended identity, then query a known passage before relying on the corpus. Use stable keys when refreshing sections; omitted sections are not automatically deleted. Enumerated chunks expose id and stored channel. To update a channel-bearing chunk through /api/mcp/update, supply that scope as scopeChannel and the intended agentId. To forget it through /api/mcp/forget, supply the scope as channel. A management inventory does not bypass by-ID visibility checks.

​
Errors and common mistakes

A failed import can leave earlier chunks saved. Retrying with stable keys avoids appending duplicates. A successful empty query can reflect access rather than lack of content. Do not assume the owner’s management list and an agent’s retrieval list are identical. Use agentIds: null only when you intend to open access throughout the account; an empty array closes it. To share a reference across identities, set the intended allow-list rather than inventing a special channel name. Separate accounts remain the security boundary.