Knowledge Bases

Knowledge bases store documents, URLs, and structured data that agents use for retrieval-augmented generation (RAG). Each KB has its own vector index, document registry, and optional knowledge graph.

All API requests require a valid JWT token in the Authorization: Bearer <token> header. The API Gateway decodes the JWT and forwards auth context (user-id, organization-id, user-email, x-platform-role, x-org-role) as headers to downstream services.

Create Knowledge Base

Create a new knowledge base in your organization.

Request Body

string

required

Knowledge base name.

string

Description of the knowledge base contents.

string

default:"private"

Visibility: private, shared, or public.

object

Custom KB settings (embedding config, chunking strategy, etc.).

Response (201)

object

The created knowledge base.

Show Knowledge base object

string

KB UUID.

string

KB name.

string

KB description.

string

Owning organization UUID.

string

Visibility level.

object

KB settings.

string

ISO 8601 timestamp.

string

ISO 8601 timestamp.

curl -X POST https://your-domain.com/api/knowledge/kb \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Help Center Articles",
    "description": "Customer support documentation",
    "visibility": "shared"
  }'

const response = await fetch("https://your-domain.com/api/knowledge/kb", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${token}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    name: "Help Center Articles",
    description: "Customer support documentation",
    visibility: "shared",
  }),
});

const { knowledgeBase } = await response.json();

List Knowledge Bases

List all knowledge bases in your organization.

Query Parameters

number

default:"50"

Maximum results.

number

default:"0"

Pagination offset.

Response (200)

object[]

Array of KB objects.

number

Total count.

number

Applied limit.

number

Applied offset.

curl

curl https://your-domain.com/api/knowledge/kb?limit=20 \
  -H "Authorization: Bearer $TOKEN"

Get Knowledge Base

Get a single knowledge base with full details.

Path Parameters

string

required

KB UUID.

Response (200)

object

Full KB object.

Update Knowledge Base

Update knowledge base metadata.

Path Parameters

string

required

KB UUID.

Request Body

string

Updated name.

string

Updated description.

string

Updated visibility.

object

Updated settings.

Response (200)

Returns the updated KB object.

Delete Knowledge Base

Permanently delete a knowledge base, including all documents, chunks, vectors, and graph data.

Path Parameters

string

required

KB UUID.

Response (204)

No content on success.

This action is irreversible. All documents, embeddings, and knowledge graph data for this KB will be permanently deleted.

Link Agent to KB

Link a knowledge base to an agent, enabling RAG context retrieval for that agent’s conversations.

Path Parameters

string

required

KB UUID.

string

required

Agent UUID.

Request Body

object

Optional permission overrides for this link.

number

default:"0"

Priority level for search result ranking when multiple KBs are linked.

Response (200)

{
  "message": "Agent linked to knowledge base successfully",
  "knowledgeBaseId": "kb-uuid",
  "agentId": "agent-uuid"
}

curl -X POST https://your-domain.com/api/knowledge/kb/KB_ID/agents/AGENT_ID \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"priority": 1}'

await fetch(
  `https://your-domain.com/api/knowledge/kb/${kbId}/agents/${agentId}`,
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${token}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ priority: 1 }),
  }
);

Unlink Agent from KB

Remove the link between a knowledge base and an agent.

Path Parameters

string

required

KB UUID.

string

required

Agent UUID.

Response (200)

{
  "message": "Agent unlinked successfully"
}

Get Agent’s Linked KBs

Get all knowledge bases linked to a specific agent.

Path Parameters

string

required

Agent UUID.

Response (200)

object[]

Array of KB objects with link metadata (permissions, priority, linked_at).

number

Number of linked KBs.

Getting Started

Agent Provisioning

Bot Service

Auth Service

Knowledge Service

Knowledge Bases

Knowledge Bases

Create Knowledge Base

Request Body

Response (201)

List Knowledge Bases

Query Parameters

Response (200)

Get Knowledge Base

Path Parameters

Response (200)

Update Knowledge Base

Path Parameters

Request Body

Response (200)

Delete Knowledge Base

Path Parameters

Response (204)

Link Agent to KB

Path Parameters

Request Body

Response (200)

Unlink Agent from KB

Path Parameters

Response (200)

Get Agent’s Linked KBs

Path Parameters

Response (200)

​Knowledge Bases

​Create Knowledge Base

​Request Body

​Response (201)

​List Knowledge Bases

​Query Parameters

​Response (200)

​Get Knowledge Base

​Path Parameters

​Response (200)

​Update Knowledge Base

​Path Parameters

​Request Body

​Response (200)

​Delete Knowledge Base

​Path Parameters

​Response (204)

​Link Agent to KB

​Path Parameters

​Request Body

​Response (200)

​Unlink Agent from KB

​Path Parameters

​Response (200)

​Get Agent’s Linked KBs

​Path Parameters

​Response (200)

Knowledge Bases

Create Knowledge Base

Request Body

Response (201)

List Knowledge Bases

Query Parameters

Response (200)

Get Knowledge Base

Path Parameters

Response (200)

Update Knowledge Base

Path Parameters

Request Body

Response (200)

Delete Knowledge Base

Path Parameters

Response (204)

Link Agent to KB

Path Parameters

Request Body

Response (200)

Unlink Agent from KB

Path Parameters

Response (200)

Get Agent’s Linked KBs

Path Parameters

Response (200)