Skip to main content
The Knowledge Base endpoints let you create and manage reference collections, import chunks, and query them directly. All requests require an Authorization: Bearer <your-api-key> header. See Authentication for details. All endpoints honor per-user tenancy — you can only access Knowledge Bases owned by your account — and respect optional scope boundaries so reference data stays isolated by client, workspace, or agent lane.

​
GET /api/knowledge-bases

List all Knowledge Bases in your account. Optionally filter by scope or agent.

​
Query parameters

​
scope
string
Return only Knowledge Bases whose scope matches this string. Pass the channel identifier for the current workspace or client.
​
agentId
string
Return only Knowledge Bases visible to this agent ID. An agent ID is the portion of a channel string before the first colon — for example, channel my-agent:session-1 has agent ID my-agent.

​
Response

​
knowledgeBases
object[]
Array of Knowledge Base objects.
curl "https://your-deployment.convex.site/api/knowledge-bases?scope=acme-corp" \
  -H "Authorization: Bearer mc_your_api_key"

{
  "knowledgeBases": [
    {
      "_id": "jx7k2m9p4n8q",
      "name": "Product documentation",
      "description": "Public-facing docs for the v2 API",
      "scope": "acme-corp",
      "memoryCount": 284,
      "totalChars": 481920,
      "isActive": true,
      "createdAt": 1711929600000,
      "updatedAt": 1712016000000
    }
  ]
}

​
POST /api/knowledge-bases

Create a new Knowledge Base.

​
Request body

​
name
string
required
Display name for the Knowledge Base.
​
description
string
Optional description explaining what this KB contains.
​
scope
string
Scope string that restricts visibility. Only agents operating in a channel matching this scope can see the KB. Omit to make the KB visible to all your agents.
​
agentIds
string[]
Further restrict visibility to specific agent IDs. When set, only agents whose ID appears in this list can access the KB.
​
sourceType
string
Optional label for the source of the content (for example, "confluence", "github", "pdf"). Stored as metadata on each chunk.

​
Response

​
knowledgeBaseId
string
The ID of the newly created Knowledge Base. Use this in all subsequent import and query requests.
curl -X POST https://your-deployment.convex.site/api/knowledge-bases \
  -H "Authorization: Bearer mc_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Product documentation",
    "description": "Public-facing docs for the v2 API",
    "scope": "acme-corp",
    "sourceType": "confluence"
  }'

{
  "knowledgeBaseId": "jx7k2m9p4n8q"
}

​
POST /api/knowledge-bases/:knowledgeBaseId/import

Import chunks into a Knowledge Base with synchronous embedding and graph enrichment. Each chunk is stored and made immediately searchable. Use this for moderate batches where you need results available right away.

​
Path parameters

​
knowledgeBaseId
string
required
The ID of the Knowledge Base to import into.

​
Request body

​
chunks
object[]
required
Array of chunks to import.

​
Response

​
knowledgeBaseId
string
The KB ID.
​
importedCount
number
Number of chunks successfully imported.
​
memoryIds
string[]
IDs of the created memory records.
​
memoryCount
number
Updated total chunk count for the KB.
​
totalChars
number
Updated total character count for the KB.
curl -X POST https://your-deployment.convex.site/api/knowledge-bases/jx7k2m9p4n8q/import \
  -H "Authorization: Bearer mc_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "chunks": [
      {
        "content": "The capture endpoint stores a memory with the provided title and content.",
        "metadata": {
          "title": "POST /api/mcp/capture",
          "sourceUrl": "https://docs.acme.com/api/capture",
          "chunkIndex": 0,
          "totalChunks": 12
        }
      }
    ]
  }'

{
  "knowledgeBaseId": "jx7k2m9p4n8q",
  "importedCount": 1,
  "memoryIds": ["mem_def456"],
  "memoryCount": 285,
  "totalChars": 482000
}

​
POST /api/knowledge-bases/:knowledgeBaseId/bulk-insert

Insert a large batch of chunks without the per-request embedding overhead. Rows are written immediately; embedding and graph enrichment are scheduled automatically and run in the background. Use this for high-volume backfills and large migrations.
Maximum 100 chunks per request. For larger datasets, split your payload into batches of 100 and send multiple requests sequentially.

​
Path parameters

​
knowledgeBaseId
string
required
The ID of the Knowledge Base to insert into.

​
Request body

​
chunks
object[]
required
Array of chunks to insert.

​
Response

​
importedCount
number
Number of chunks written. Chunks that fail the content security scanner are skipped silently.
​
memoryIds
string[]
IDs of the created memory records.
curl -X POST https://your-deployment.convex.site/api/knowledge-bases/jx7k2m9p4n8q/bulk-insert \
  -H "Authorization: Bearer mc_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "chunks": [
      {
        "title": "Quickstart — install",
        "content": "Run curl -fsSL https://memorycrystal.ai/crystal | bash to install Memory Crystal.",
        "chunkIndex": 0,
        "totalChunks": 50,
        "sourceType": "docs"
      },
      {
        "title": "Quickstart — connect",
        "content": "After install, connect your AI host by following the integration guide for your client.",
        "chunkIndex": 1,
        "totalChunks": 50,
        "sourceType": "docs"
      }
    ]
  }'

{
  "importedCount": 2,
  "memoryIds": ["mem_ghi789", "mem_jkl012"]
}

​
POST /api/knowledge-bases/:knowledgeBaseId/query

Query a Knowledge Base directly. Returns ranked chunks matching the query using hybrid semantic and text search.

​
Path parameters

​
knowledgeBaseId
string
required
The ID of the Knowledge Base to search.

​
Request body

​
query
string
required
Natural-language question or keyword phrase.
​
limit
number
default:"8"
Maximum number of chunks to return. Capped at 20.
​
agentId
string
Agent ID to use for visibility checks. Defaults to the agent ID derived from the channel parameter.
​
channel
string
Channel string for scope matching. Used to enforce scope restrictions and derive the agent ID.

​
Response

​
knowledgeBase
object
Metadata for the queried Knowledge Base.
​
memories
object[]
Ranked array of matching chunks.
curl -X POST https://your-deployment.convex.site/api/knowledge-bases/jx7k2m9p4n8q/query \
  -H "Authorization: Bearer mc_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "How do I authenticate API requests?",
    "limit": 5,
    "channel": "acme-corp"
  }'

{
  "knowledgeBase": {
    "_id": "jx7k2m9p4n8q",
    "name": "Product documentation",
    "memoryCount": 284
  },
  "memories": [
    {
      "memoryId": "mem_def456",
      "title": "Authentication overview",
      "content": "All API endpoints require an Authorization: Bearer header with a valid API key.",
      "score": 0.94,
      "tags": ["api", "auth"]
    }
  ]
}
If a Knowledge Base has a scope set, you must pass a matching channel in the query body or the request returns an empty result array. This is by design — scope restrictions are enforced at query time to maintain workspace isolation.