{"openapi":"3.1.0","info":{"title":"KB API","version":"1.0.0","description":"The KB API lets you query document-grounded knowledge bots programmatically — grounded, cited answers from your own documentation, FAQs, and support content. Built for human developers, AI agents, and automated workflows.","contact":{"name":"KB Support","url":"https://kb.example.com"}},"servers":[{"url":"https://knowledge.aivera.nl/api","description":"Production"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"kb_live_<key>","description":"Get your API key at https://kb.example.com/settings/api"}},"schemas":{"Error":{"type":"object","properties":{"data":{"type":"null"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}},"BalanceResponse":{"type":"object","properties":{"balance_millicents":{"type":"integer","description":"100,000 millicents = $1.00"},"balance_usd":{"type":"string"},"type":{"type":"string","enum":["tenant"]}}},"Bot":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"is_public":{"type":"boolean"},"model":{"type":"string"},"created_at":{"type":"string","format":"date-time"}}},"Message":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"role":{"type":"string","enum":["user","assistant"]},"content":{"type":"string"},"sources":{"type":"array","items":{"$ref":"#/components/schemas/SourceCitation"}},"created_at":{"type":"string","format":"date-time"}}},"SourceCitation":{"type":"object","properties":{"chunk_id":{"type":"string"},"source_name":{"type":"string"},"url":{"type":"string","nullable":true},"score":{"type":"number","description":"Cosine similarity (0–1)"},"excerpt":{"type":"string"}}}}},"paths":{"/bots":{"get":{"operationId":"listBots","summary":"List your bots","tags":["Bots"],"responses":{"200":{"description":"List of bots","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Bot"}},"error":{"type":"null"}}}}}}}}},"/bots/{botId}/chat":{"post":{"operationId":"chat","summary":"Chat with a bot","description":"Send a message to a bot and get a RAG-powered reply. Supports streaming via SSE when `stream: true`.","tags":["Chat"],"parameters":[{"name":"botId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["message"],"properties":{"message":{"type":"string","description":"User message"},"conversation_id":{"type":"string","description":"Continue an existing conversation"},"external_id":{"type":"string","description":"Your own session identifier (e.g. Cursor session ID)"},"stream":{"type":"boolean","default":true,"description":"Return SSE stream instead of JSON"},"include_sources":{"type":"boolean","default":true},"top_k":{"type":"integer","default":5,"minimum":1,"maximum":20},"temperature":{"type":"number","default":0.3,"minimum":0,"maximum":1},"images":{"type":"array","description":"Base64-encoded images to attach (max 3). Client should resize to max 2048px and compress to JPEG.","maxItems":3,"items":{"type":"object","required":["data","media_type"],"properties":{"data":{"type":"string","description":"Base64-encoded image data (no data URI prefix)"},"media_type":{"type":"string","enum":["image/jpeg","image/png","image/gif","image/webp"]}}}}}}}}},"responses":{"200":{"description":"Chat response. When `stream: false`, returns JSON. When `stream: true`, returns SSE.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"conversation_id":{"type":"string"},"message":{"$ref":"#/components/schemas/Message"},"usage":{"type":"object","properties":{"prompt_tokens":{"type":"integer"},"completion_tokens":{"type":"integer"}}}}},"error":{"type":"null"}}}},"text/event-stream":{"schema":{"type":"string"},"example":"event: sources\ndata: {\"sources\":[...]}\n\nevent: delta\ndata: {\"text\":\"...\"}\n\nevent: done\ndata: {\"conversation_id\":\"...\",\"usage\":{...}}\n\n"}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Bot not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/bots/{botId}/ingest":{"post":{"operationId":"ingestSource","summary":"Add a knowledge source to a bot","tags":["Sources"],"parameters":[{"name":"botId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["type","name"],"properties":{"type":{"type":"string","enum":["url","pdf","text","markdown","docx","sitemap","docsite","youtube","rss","github","github_releases","gitbook","openapi","x_post","wrpc","pnn","npmjs"]},"name":{"type":"string"},"url":{"type":"string","format":"uri"},"content":{"type":"string"}}}},"multipart/form-data":{"schema":{"type":"object","properties":{"type":{"type":"string","enum":["url","pdf","text","markdown","docx","sitemap","docsite","youtube","rss","github","github_releases","gitbook","openapi","x_post","wrpc","pnn","npmjs"]},"name":{"type":"string"},"file":{"type":"string","format":"binary"}}}}}},"responses":{"202":{"description":"Ingestion job started"},"401":{"description":"Unauthorized"}}}},"/mcp":{"post":{"operationId":"mcpEndpoint","summary":"MCP server endpoint","description":"Model Context Protocol endpoint for AI coding assistants. Connect via Claude Code, Cursor, Windsurf, or Continue.dev.","tags":["MCP"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"jsonrpc":{"type":"string","enum":["2.0"]},"method":{"type":"string"},"params":{"type":"object"},"id":{"type":["string","number"]}}}}}},"responses":{"200":{"description":"JSON-RPC 2.0 response"}}}},"/payments/balance":{"get":{"operationId":"getBalance","summary":"Check prepaid balance","description":"Returns the current prepaid balance for the authenticated tenant. Auth via Bearer API key.","tags":["Payments"],"responses":{"200":{"description":"Current balance","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BalanceResponse"}}}},"401":{"description":"Unauthorized — Bearer API key required"}}}},"/workflows":{"get":{"operationId":"listWorkflows","summary":"List workflow definitions","description":"Returns all active workflows for agents to match and execute locally. Free — no billing. Supports filtering by intent, project, category, ecosystem, and tags.","tags":["Workflows"],"parameters":[{"name":"intent","in":"query","schema":{"type":"string"},"description":"Filter by intent (e.g., lookup.record or lookup.* for prefix match)"},{"name":"project","in":"query","schema":{"type":"string"},"description":"Filter by project slug"},{"name":"category","in":"query","schema":{"type":"string"},"description":"Filter by category (e.g., search, integrations, support)"},{"name":"ecosystem","in":"query","schema":{"type":"string"},"description":"Filter by ecosystem (execution context)"},{"name":"tags","in":"query","schema":{"type":"string"},"description":"Comma-separated tags (all must match)"},{"name":"since","in":"query","schema":{"type":"string","format":"date-time"},"description":"ISO 8601 — incremental sync"},{"name":"active_only","in":"query","schema":{"type":"boolean","default":true}}],"responses":{"200":{"description":"Workflow registry response with workflows, parsers, error handlers"}}}},"/workflows/projects":{"get":{"operationId":"listWorkflowProjects","summary":"List projects in the workflow registry","description":"Returns all projects with workflow counts and supported intents. Discovery endpoint — no billing.","tags":["Workflows"],"responses":{"200":{"description":"Project list with workflow counts and intent arrays"}}}},"/workflows/tools":{"get":{"operationId":"listWorkflowTools","summary":"List canonical tools referenced by workflows","description":"Returns tool definitions with parameter and output schemas for agent SDK validation.","tags":["Workflows"],"responses":{"200":{"description":"Tool list with schemas"}}}},"/workflows/docs":{"get":{"operationId":"getWorkflowDocs","summary":"Human-readable workflow documentation","description":"Returns markdown documentation of all workflows, tools, and execution model. No auth required.","tags":["Workflows"],"security":[],"responses":{"200":{"description":"Markdown documentation","content":{"text/markdown":{"schema":{"type":"string"}}}}}}},"/workflows/report":{"post":{"operationId":"reportWorkflowExecution","summary":"Report workflow execution outcome","description":"Agents report whether a workflow was executed, succeeded, or failed. Feeds trust metrics and reputation tracking.","tags":["Workflows"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["workflow_slug","executed"],"properties":{"workflow_slug":{"type":"string"},"executed":{"type":"boolean"},"success":{"type":"boolean"},"execution_time_ms":{"type":"number"},"error":{"type":"string"},"source":{"type":"string","enum":["sdk","web","mcp","a2a"]}}}}}},"responses":{"200":{"description":"Execution recorded"}}}}}}