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. Requires the member organization role or higher (platform superadmins always pass).

There is no visibility field. Access to a knowledge base is decided by organization membership plus per-resource grants. A visibility key sent in a create or update body is ignored (BSIO-449).

Request Body

string

required

Knowledge base name.

string

Description of the knowledge base contents.

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.

object

KB settings.

string

ISO 8601 timestamp.

string

ISO 8601 timestamp.

Errors

error

The caller’s organization role is below member. Nothing is created. Body: { "error": "Forbidden", "message": "Requires member role or higher" }.

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"
  }'

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",
  }),
});

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.

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. Requires delete on the knowledge base. Its agent links are removed with it (kb_agent_links cascades) — no agent is deleted, and agents that used it keep answering without it. Writes a knowledge_base.delete audit entry, and attributes the vector-store cost, to the organization that owned the knowledge base (they differ from the caller’s only for a superadmin).

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. Requires edit on the knowledge base and edit on the agent. Org owners, admins and members have both on everything in their organization; a viewer needs a grant on each. The knowledge base and the agent must belong to the same organization. Writes a knowledge_base.agent_link audit entry under the knowledge base’s organization. Linking an already-linked pair updates its permissions and priority.

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"
}

Errors

Status	Body	When
403	`{ "error": "Forbidden", "message": "…" }`	The caller lacks `edit` on the knowledge base or on the agent (a viewer without a grant).
404	`{ "error": "Not found" }`	The knowledge base or agent does not exist, is deleted, or belongs to another organization — deliberately indistinguishable.
409	`{ "error": "Conflict", "message": "…" }`	Both exist but belong to different organizations. Only a platform superadmin can reach this; cross-organization links are refused for every caller.

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. Requires edit on the knowledge base and edit on the agent, like linking. Idempotent: unlinking a pair that is not linked still returns 200. Writes a knowledge_base.agent_unlink audit entry under the knowledge base’s organization when a link was actually removed. A platform superadmin may remove a link whose two sides are in different organizations (a link created before cross-organization links were refused); everyone else gets 404 for an agent outside their organization.

Path Parameters

string

required

KB UUID.

string

required

Agent UUID.

Response (200)

{
  "message": "Agent unlinked successfully"
}

Errors

Status	Body	When
403	`{ "error": "Forbidden", "message": "…" }`	The caller lacks `edit` on the knowledge base or on the agent.
404	`{ "error": "Not found" }`	The knowledge base or agent does not exist or belongs to another organization (non-superadmin callers).

Get KB’s Linked Agents

Get all agents linked to a specific knowledge base — the reverse lookup of Get Agent’s Linked KBs. Powers the KB Overview page’s Connected Agents card.

Path Parameters

string

required

KB UUID.

Response (200)

object[]

Array of linked agents, ordered by link priority (descending) then link creation time.

Show Agent object

string

Agent (bot) UUID.

string

Agent name.

string

draft, published, or archived.

number

Link priority from kb_agent_links.

Soft-deleted agents (deleted_at IS NOT NULL) are excluded.

curl

curl https://your-domain.com/api/knowledge/kb/KB_ID/agents \
  -H "Authorization: Bearer $TOKEN"

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)

Errors

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)

Errors

Unlink Agent from KB

Path Parameters

Response (200)

Errors

Get KB’s Linked Agents

Path Parameters

Response (200)

Get Agent’s Linked KBs

Path Parameters

Response (200)

​Knowledge Bases

​Create Knowledge Base

​Request Body

​Response (201)

​Errors

​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)

​Errors

​Unlink Agent from KB

​Path Parameters

​Response (200)

​Errors

​Get KB’s Linked Agents

​Path Parameters

​Response (200)

​Get Agent’s Linked KBs

​Path Parameters

​Response (200)

Knowledge Bases

Create Knowledge Base

Request Body

Response (201)

Errors

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)

Errors

Unlink Agent from KB

Path Parameters

Response (200)

Errors

Get KB’s Linked Agents

Path Parameters

Response (200)

Get Agent’s Linked KBs

Path Parameters

Response (200)