Knowledge Bases - brightstack AI

This guide covers how to create and manage Knowledge Bases (KBs), index and de-index content for semantic search, perform searches, and manage Entities and Relationships. For agent integration using MCP tools, see the MCP guide.

Create and manage Knowledge Bases

Use the Catalog API to create, list, update, and delete KBs.

POST /v1/catalog/knowledge-bases
{
  "name": "product-docs",
  "displayName": "Product Documentation",
  "description": "Technical documentation and guides",
  "enabled": true
}

GET /v1/catalog/knowledge-bases

GET /v1/catalog/knowledge-bases/:idOrName

PATCH /v1/catalog/knowledge-bases/:idOrName
{
  "displayName": "Docs",
  "enabled": true
}

DELETE /v1/catalog/knowledge-bases/:idOrName

Notes

Each KB has an isolated vector collection.
Default KB “general” exists for every organization.

Index and de-index content

Index Entities asynchronously and Relationships synchronously into the KB’s vector store.

POST /v1/search/index
{
  "entity": {
    "type": "Document",
    "content": { "type": "text", "text": "This is the content..." },
    "properties": { "title": "Getting Started" }
  },
  "kb": "product-docs"
}

POST /v1/search/index/connect
{
  "relationship": { "type": "references" },
  "source": { "id": "ent_123" },
  "target": { "id": "ent_456" },
  "kb": "product-docs"
}

POST /v1/search/deindex
{
  "id": "ent_123",
  "objectType": "Entity", // or "Relationship"
  "kb": "product-docs"
}

Tips

Large files should be indexed asynchronously.
Provide meaningful properties (e.g., title, category) to improve filtering.

Search

Perform semantic search across Entities and Relationships within a KB.

POST /v1/search
{
  "query": "how to implement authentication",
  "kb": "product-docs",
  "limit": 10,
  "objectType": "Entity",
  "types": ["Document", "Guide"],
  "properties": { "category": "documentation" }
}

Features

Vector similarity ranking with configurable score threshold
Filtering by object type, types, and properties
Pagination with limit/offset

Manage Entities and Relationships

Entities represent nodes (documents, objects) with content and metadata. Relationships connect Entities.

POST /v1/entities
{
  "knowledgeBaseId": "kb_abc123",
  "type": "Document",
  "externalId": "doc-123",
  "content": { "type": "text", "text": "This is the document content..." },
  "properties": { "title": "Getting Started", "category": "documentation" }
}

POST /v1/relationships
{
  "type": "references",
  "sourceId": "ent_123",
  "targetId": "ent_456",
  "properties": { "notes": "Cites paragraph 2" }
}

Guidance

Choose appropriate entity types; keep property schemas consistent.
Use timestamps for time-aware queries.

MCP tools (overview)

Agents can access KBs and perform search via MCP tools (covered in-depth separately). You can: list KBs, run semantic search, and execute query models from an agent environment. See the MCP guide for setup and examples.

​Create and manage Knowledge Bases

​Notes

​Index and de-index content

​Tips

​Search

​Features

​Manage Entities and Relationships

​Guidance

​MCP tools (overview)