Sources API 🟡 BETA

Unified interface for managing knowledge bases, MCP integrations, and browsing available resources.

Base URL

/api/ui/sources

Authentication

All endpoints require a valid session token via Authorization: Bearer <token> header.

Knowledge Base (KB) Endpoints

List Knowledge Bases

GET /api/ui/sources/kb/

Returns all knowledge base configurations for the authenticated bot.

Response:

[
  {
    "id": "kb-001",
    "name": "Product Manual",
    "description": "Complete product documentation",
    "documentCount": 42,
    "chunkCount": 310,
    "created_at": "2026-01-15T10:30:00Z",
    "updated_at": "2026-05-20T14:22:00Z"
  }
]

Create Knowledge Base

POST /api/ui/sources/kb/

Creates a new knowledge base bucket for the bot.

ParameterTypeRequiredDescription
namestringYesHuman-readable KB name
descriptionstringNoDescription of the KB purpose
chunkSizeintegerNoToken chunk size (default: 512)
chunkOverlapintegerNoOverlap between chunks (default: 50)

Request:

{
  "name": "Support FAQ",
  "description": "Frequently asked questions from support tickets",
  "chunkSize": 512,
  "chunkOverlap": 50
}

Response:

{
  "id": "kb-faq-001",
  "name": "Support FAQ",
  "description": "Frequently asked questions from support tickets",
  "documentCount": 0,
  "chunkCount": 0,
  "created_at": "2026-06-04T12:00:00Z"
}

Query Knowledge Base

POST /api/ui/sources/kb/query

Searches a KB with semantic similarity and returns relevant chunks for LLM context injection.

ParameterTypeRequiredDescription
kbIdstringYesKnowledge base identifier
querystringYesNatural language query
topKintegerNoMax results to return (default: 5)
thresholdnumberNoMin similarity score 0.0–1.0 (default: 0.7)

Request:

{
  "kbId": "kb-001",
  "query": "How do I reset the admin password?",
  "topK": 3,
  "threshold": 0.75
}

Response:

{
  "results": [
    {
      "chunkId": "chunk-101",
      "documentId": "doc-12",
      "content": "To reset the admin password, navigate to Settings > Security > Password Reset...",
      "score": 0.94,
      "metadata": {
        "source": "admin-guide.pdf",
        "page": 14
      }
    }
  ],
  "queryTimeMs": 42
}

Reindex Knowledge Base

POST /api/ui/sources/kb/reindex

Triggers a full reindex of all documents in a KB. Useful after bulk uploads or schema changes.

ParameterTypeRequiredDescription
kbIdstringYesKnowledge base identifier

Request:

{
  "kbId": "kb-001"
}

Response:

{
  "status": "reindex_started",
  "kbId": "kb-001",
  "estimatedChunks": 310
}

Get Knowledge Base Stats

GET /api/ui/sources/kb/stats

Returns aggregate statistics for a knowledge base.

ParameterTypeRequiredDescription
kbIdstringYesKnowledge base identifier (query param)

Request:

GET /api/ui/sources/kb/stats?kbId=kb-001

Response:

{
  "kbId": "kb-001",
  "name": "Product Manual",
  "documentCount": 42,
  "chunkCount": 310,
  "totalTokens": 158720,
  "avgChunkTokens": 512,
  "lastIndexed": "2026-05-20T14:22:00Z",
  "vectorStoreSizeBytes": 26214400
}

Delete Knowledge Base

DELETE /api/ui/sources/kb/:id

Permanently removes a knowledge base and all its documents and vectors.

ParameterTypeRequiredDescription
idstringYesKB identifier (path param)

Request:

DELETE /api/ui/sources/kb/kb-001

Response:

{
  "deleted": true,
  "id": "kb-001"
}

MCP (Model Context Protocol) Endpoints

Scan MCP Servers

POST /api/ui/sources/mcp/scan

Scans configured MCP servers and discovers available tools.

ParameterTypeRequiredDescription
urlsstring[]NoSpecific server URLs to scan (empty = all configured)

Request:

{
  "urls": ["http://localhost:8082", "http://10.0.0.5:9000"]
}

Response:

{
  "scanned": 2,
  "discoveredTools": 18,
  "servers": [
    {
      "url": "http://localhost:8082",
      "name": "local-tools",
      "toolCount": 12,
      "status": "healthy"
    },
    {
      "url": "http://10.0.0.5:9000",
      "name": "data-service",
      "toolCount": 6,
      "status": "healthy"
    }
  ]
}

List MCP Examples

GET /api/ui/sources/mcp/examples

Returns example MCP server configurations and usage patterns.

Response:

[
  {
    "name": "Filesystem Server",
    "url": "http://localhost:8082",
    "description": "Local filesystem access for reading/writing files",
    "tools": ["read_file", "write_file", "list_directory"]
  },
  {
    "name": "Database Server",
    "url": "http://localhost:8083",
    "description": "PostgreSQL query execution and schema inspection",
    "tools": ["query", "list_tables", "describe_table"]
  }
]

List All MCP Tools

GET /api/ui/sources/mcp/tools

Returns a flat list of all tools discovered across all MCP servers.

Response:

[
  {
    "server": "local-tools",
    "name": "read_file",
    "description": "Read contents of a file",
    "inputSchema": {
      "type": "object",
      "properties": {
        "path": { "type": "string", "description": "File path" }
      },
      "required": ["path"]
    }
  },
  {
    "server": "data-service",
    "name": "query",
    "description": "Execute a SQL query",
    "inputSchema": {
      "type": "object",
      "properties": {
        "sql": { "type": "string", "description": "SQL statement" }
      },
      "required": ["sql"]
    }
  }
]

Test MCP Server

POST /api/ui/sources/mcp/:name/test

Tests connectivity and tool availability for a specific MCP server.

ParameterTypeRequiredDescription
namestringYesMCP server name (path param)

Request:

POST /api/ui/sources/mcp/local-tools/test

Response:

{
  "server": "local-tools",
  "status": "healthy",
  "latencyMs": 12,
  "toolCount": 12,
  "version": "1.0.3"
}

Get MCP Server Tools

GET /api/ui/sources/mcp/:name/tools

Returns tools for a specific MCP server.

ParameterTypeRequiredDescription
namestringYesMCP server name (path param)

Request:

GET /api/ui/sources/mcp/local-tools/tools

Response:

{
  "server": "local-tools",
  "tools": [
    {
      "name": "read_file",
      "description": "Read contents of a file",
      "inputSchema": {
        "type": "object",
        "properties": {
          "path": { "type": "string" }
        },
        "required": ["path"]
      }
    },
    {
      "name": "write_file",
      "description": "Write content to a file",
      "inputSchema": {
        "type": "object",
        "properties": {
          "path": { "type": "string" },
          "content": { "type": "string" }
        },
        "required": ["path", "content"]
      }
    }
  ]
}

Enable/Disable MCP Server

POST /api/ui/sources/mcp/:name/enable

Enables or disables an MCP server for bot tool usage.

ParameterTypeRequiredDescription
namestringYesMCP server name (path param)
enabledbooleanYesWhether to enable or disable

Request:

{
  "enabled": true
}

Response:

{
  "server": "local-tools",
  "enabled": true,
  "activeToolCount": 12
}

Browse Endpoints

List Repositories

GET /api/ui/sources/repositories

Returns available code repositories.

Response:

[
  {
    "id": "repo-1",
    "name": "botserver",
    "url": "https://github.com/org/botserver",
    "branch": "main",
    "lastSync": "2026-06-04T08:00:00Z"
  }
]

List Apps

GET /api/ui/sources/apps

Returns available HTMX applications.

Response:

[
  {
    "id": "app-dashboard",
    "name": "Dashboard",
    "path": "/apps/dashboard",
    "description": "Main analytics dashboard"
  }
]

List Prompts

GET /api/ui/sources/prompts

Returns saved prompt templates.

Response:

[
  {
    "id": "prompt-01",
    "name": "Summarizer",
    "template": "Summarize the following text in 3 bullet points:\n\n{{text}}",
    "variables": ["text"]
  }
]

List Templates

GET /api/ui/sources/templates

Returns available email and document templates.

Response:

[
  {
    "id": "tpl-welcome",
    "name": "Welcome Email",
    "type": "email",
    "subject": "Welcome to {{company}}"
  }
]

List News

GET /api/ui/sources/news

Returns recent news items or changelog entries.

Response:

[
  {
    "id": "news-001",
    "title": "MCP Server Support Added",
    "date": "2026-06-01",
    "summary": "New integration with Model Context Protocol servers for extended tool access."
  }
]

List MCP Servers

GET /api/ui/sources/mcp-servers

Returns all configured MCP servers with status.

Response:

[
  {
    "name": "local-tools",
    "url": "http://localhost:8082",
    "enabled": true,
    "status": "healthy",
    "toolCount": 12
  }
]

List LLM Tools

GET /api/ui/sources/llm-tools

Returns built-in LLM tools available to the bot.

Response:

[
  {
    "id": "tool-web-search",
    "name": "Web Search",
    "description": "Search the web for information",
    "enabled": true
  },
  {
    "id": "tool-code-exec",
    "name": "Code Execution",
    "description": "Execute Python/JS code in sandbox",
    "enabled": false
  }
]

List Models

GET /api/ui/sources/models

Returns available LLM models.

Response:

[
  {
    "id": "gpt-4o",
    "provider": "openai",
    "contextWindow": 128000,
    "maxOutput": 16384
  },
  {
    "id": "claude-sonnet-4-20250514",
    "provider": "anthropic",
    "contextWindow": 200000,
    "maxOutput": 8192
  }
]

Search Sources

GET /api/ui/sources/search

Performs a unified search across all sources.

ParameterTypeRequiredDescription
qstringYesSearch query (query param)
typestringNoFilter by type: kb, mcp, app, prompt

Request:

GET /api/ui/sources/search?q=password+reset&type=kb

Response:

{
  "query": "password reset",
  "results": [
    {
      "type": "kb",
      "sourceId": "kb-001",
      "sourceName": "Product Manual",
      "match": "To reset the admin password, navigate to Settings...",
      "score": 0.92
    }
  ],
  "totalResults": 1
}

List Mentions

GET /api/ui/sources/mentions

Returns available mention triggers for bot commands.

Response:

[
  {
    "trigger": "@search",
    "description": "Search knowledge bases",
    "handler": "kb_search"
  },
  {
    "trigger": "@tool",
    "description": "Execute an MCP tool",
    "handler": "mcp_execute"
  }
]

API Keys

List API Keys

GET /api/ui/sources/api-keys

Returns all API keys for the bot.

Response:

[
  {
    "id": "key-001",
    "name": "Production Key",
    "prefix": "gbo_****_a3f2",
    "scopes": ["kb:read", "mcp:execute"],
    "createdAt": "2026-03-10T09:00:00Z",
    "expiresAt": "2027-03-10T09:00:00Z"
  }
]

Create API Key

POST /api/ui/sources/api-keys

Creates a new API key.

ParameterTypeRequiredDescription
namestringYesHuman-readable key name
scopesstring[]YesPermission scopes
expiresInDaysintegerNoTTL in days (default: 365)

Request:

{
  "name": "CI Pipeline Key",
  "scopes": ["kb:read", "kb:write"],
  "expiresInDays": 90
}

Response:

{
  "id": "key-002",
  "name": "CI Pipeline Key",
  "key": "gbo_live_k8x2m9p4q1r7...",
  "prefix": "gbo_****_q1r7",
  "scopes": ["kb:read", "kb:write"],
  "createdAt": "2026-06-04T12:00:00Z",
  "expiresAt": "2026-09-02T12:00:00Z"
}

Note: The full key is only shown once at creation time.

Delete API Key

DELETE /api/ui/sources/api-keys/:id

Permanently revokes an API key.

ParameterTypeRequiredDescription
idstringYesAPI key identifier (path param)

Request:

DELETE /api/ui/sources/api-keys/key-002

Response:

{
  "deleted": true,
  "id": "key-002"
}

Skills & Prompts

POST /api/ui/skills/install              # { name, bot_id } install a skill
POST /api/ui/sources/prompts/save        # form { prompt_id, collection, prompt }
POST /api/ui/sources/mcp/add-from-catalog # form { server_id } add catalog MCP server

See Also