Knowledge Base API

Manage knowledge bases, wiki pages, sources, and configuration.

Base URL: https://api.bluenexus.ai/api/v1 Auth: Bearer token with account scope

Knowledge Bases

Each account can have multiple knowledge bases. One is always the default. Pages, sources, and logs are scoped to a specific knowledge base via the :kbId path parameter.

List Knowledge Bases

GET /knowledge/bases

Returns all knowledge bases for the account. Ensures the default KB exists.

Get Knowledge Base

GET /knowledge/bases/:kbId

Create Knowledge Base

POST /knowledge/bases

Body:

{
  "name": "Product Docs",
  "description": "Product documentation and FAQs",
  "customInstructions": "Focus on extracting action items.",
  "maxPagesLimit": 500
}

Field	Required	Default	Description
`name`	Yes	—	Human-readable name (unique per account)
`description`	No	—	Description of the knowledge base
`customInstructions`	No	`""`	Custom instructions for the compilation LLM
`maxPagesLimit`	No	`500`	Maximum wiki pages allowed

Update Knowledge Base

PUT /knowledge/bases/:kbId

Body: same fields as create (all optional).

Set as Default

POST /knowledge/bases/:kbId/set-default

Atomically unsets the previous default and sets this knowledge base as the new default.

Delete Knowledge Base

DELETE /knowledge/bases/:kbId

Cannot delete the default knowledge base. Cascades: deletes all pages, sources, versions, conversation trackers, and logs in the KB.

Run Lint / Health Check

POST /knowledge/bases/:kbId/lint

Manually triggers the wiki health check (broken links, orphans, stale pages, duplicates, consolidation).

Knowledge Pages

All page endpoints are scoped to a knowledge base.

List Pages

GET /knowledge/bases/:kbId/pages

Query parameters:

Param	Type	Description
`page`	number	Page number (default: 1)
`limit`	number	Items per page (default: 20)
`tag`	string	Filter by tag
`pageType`	string	Filter by type: `entity`, `concept`, `summary`, `index`, `custom`

Get Page

GET /knowledge/bases/:kbId/pages/:slug

Returns the full page content including backlinks, confidence level, and typed relationships.

The relationships array contains typed connections to other pages:

{
  "slug": "alice-smith",
  "title": "Alice Smith",
  "content": "...",
  "confidence": "high",
  "relationships": [
    { "targetSlug": "acme-corp", "type": "works_at" },
    { "targetSlug": "project-alpha", "type": "attended" }
  ],
  "backlinks": ["team-structure", "q1-meeting-notes"]
}

Available relationship types: related_to, works_at, employed_by, founded, co_founded, attended, part_of, depends_on, mentioned_in.

Get Index

GET /knowledge/bases/:kbId/pages/index

Returns the _index page — the table of contents listing all pages.

Search Pages

GET /knowledge/bases/:kbId/pages/search?q=:query

Full-text search with content snippets. Returns matching pages ranked by relevance, boosted by backlink count (more-referenced pages rank higher).

Query parameters:

Param	Type	Description
`q`	string	Search query (required)
`tags`	string	Comma-separated tag filter (optional)

Response fields include:

Field	Type	Description
`slug`	string	Page identifier
`title`	string	Page title
`content`	string	Snippet with keyword context
`tags`	string[]	Page tags
`pageType`	string	Page type
`confidence`	string	`"low"`, `"medium"`, or `"high"` — based on source count
`updatedAt`	string	Last update timestamp

Update Page

PUT /knowledge/bases/:kbId/pages/:slug

Manually edit a page. Sets lastCompiledBy: "user" — the compiler won't overwrite user edits.

Body:

{
  "title": "Updated Title",
  "content": "Updated markdown content...",
  "tags": ["tag1", "tag2"]
}

Delete Page

DELETE /knowledge/bases/:kbId/pages/:slug

Returns 204 No Content. Triggers async lint to repair broken wiki links.

List Page Versions

GET /knowledge/bases/:kbId/pages/:slug/versions

Query parameters:

Param	Type	Description
`page`	number	Page number (default: 1)
`limit`	number	Items per page (default: 20)

Get Page Version

GET /knowledge/bases/:kbId/pages/:slug/versions/:version

Returns a specific historical version of a page.

Knowledge Sources

All source endpoints are scoped to a knowledge base.

List Sources

GET /knowledge/bases/:kbId/sources

Query parameters:

Param	Type	Description
`page`	number	Page number (default: 1)
`limit`	number	Items per page (default: 20)
`type`	string	Filter by type: `file`, `url`, `text`, `conversation`
`status`	string	Filter by status: `pending`, `processing`, `compiled`, `failed`

Get Source

GET /knowledge/bases/:kbId/sources/:sourceId

Create Source

POST /knowledge/bases/:kbId/sources

Creates a source and triggers automatic compilation.

Body:

{
  "type": "text",
  "name": "Product FAQ",
  "rawContent": "# FAQ\n\nQ: What is the pricing?\nA: ...",
  "url": "https://example.com/doc",
  "metadata": {}
}

Field	Required	Description
`type`	Yes	`"text"`, `"url"`, or `"file"`
`name`	Yes	Human-readable name
`rawContent`	For text/file	Document content
`url`	For url	URL to fetch
`metadata`	No	Additional metadata

Reprocess Source

PUT /knowledge/bases/:kbId/sources/:sourceId/reprocess

Re-triggers compilation for an existing source.

Delete Source

DELETE /knowledge/bases/:kbId/sources/:sourceId

Returns 204 No Content.

Knowledge Logs

List Logs

GET /knowledge/bases/:kbId/logs

Returns compilation and lint logs for the knowledge base.

Knowledge Config

Account-level configuration (not scoped to a specific knowledge base).

Get Config

GET /knowledge/config

Auto-creates the config if it doesn't exist.

Update Config

PUT /knowledge/config

Body:

{
  "enabled": true,
  "autoIngestConversations": true
}

Field	Type	Default	Description
`enabled`	boolean	`true`	Master toggle for the knowledge base system
`autoIngestConversations`	boolean	`false`	Auto-capture conversations after 30 min idle

Per-knowledge-base settings (customInstructions, maxPagesLimit) are configured via the knowledge base CRUD endpoints above.

Chat File Upload

Upload File

POST /v1/agents/:agentId/chat/files
Content-Type: multipart/form-data

Scope: agents-all or agents-use

Upload a file for use in chat messages. Stored in GridFS.

Field	Type	Description
`file`	binary	The file to upload (multipart form field)

Response:

{
  "fileId": "abc123...",
  "filename": "report.pdf",
  "mimeType": "application/pdf",
  "size": 245760,
  "purpose": "chat"
}

Max file size: configurable via MAX_FILE_UPLOAD_SIZE_MB env var (default: 10MB).

Supported formats: PDF, DOCX, CSV, TXT, MD, PNG, JPG, GIF, WEBP.