{"openapi":"3.1.0","info":{"title":"Knowledge Platform REST API & Retrieval Playground","version":"1.0.0","description":"\n**MCP-First, Filterable RAG Knowledge Platform**\n\nCentralized API for managing marketing & SEO documents, document sets (categories), immutable versions, and executing pre-filtered vector retrieval in Qdrant with Vertex AI embeddings.\n\n### Key Capabilities:\n- **Strict Server-Side Pre-Filtering**: Mandatory `is_active_version: true` and `document_status: published` invariants enforced before Qdrant semantic search.\n- **Multi-Format Ingestion**: Auto-extracts PDF, DOCX, Markdown, Text, HTML, and CSV.\n- **Immutable Version History**: Every document edit creates a new version; prior versions remain searchable until new versions are indexed and activated.\n- **Interactive Retrieval Playground**: Use the `POST /v1/knowledge-bases/{kbId}/retrieve` endpoint below to test vector queries with live category, date range, and tag filters.\n    "},"servers":[{"url":"http://localhost:8080","description":"Local Development Server"}],"components":{"securitySchemes":{"ProxyKeyAuth":{"type":"apiKey","in":"header","name":"x-proxy-key","description":"Shared proxy key for MCP and machine client authentication"},"BearerAuth":{"type":"http","scheme":"bearer","description":"Bearer token authorization"}},"schemas":{"KnowledgeBase":{"type":"object","properties":{"id":{"type":"string","example":"kb_01a01ac5450b7385a5d3df441c0a3e88"},"name":{"type":"string","example":"Marketcast SEO & Marketing"},"slug":{"type":"string","example":"marketcast-seo-marketing"},"description":{"type":"string","example":"Approved internal SEO documentation"},"status":{"type":"string","enum":["active","archived"],"example":"active"},"qdrantCollection":{"type":"string","example":"knowledge_chunks_v1"},"defaultEmbeddingProfile":{"type":"string","example":"text-embedding-004"},"defaultChunkingProfile":{"type":"string","example":"markdown_semantic_v1"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"DocumentSet":{"type":"object","properties":{"id":{"type":"string","example":"set_01a01ac5450b7385a5d3df441c0a3e88"},"knowledgeBaseId":{"type":"string"},"name":{"type":"string","example":"Brand & Positioning"},"slug":{"type":"string","example":"brand-positioning"},"description":{"type":"string"},"sortOrder":{"type":"integer","example":10},"status":{"type":"string","enum":["active","archived"]}}},"Document":{"type":"object","properties":{"id":{"type":"string","example":"doc_01a01ac5451b779b96ccbc94bd5b5145"},"knowledgeBaseId":{"type":"string"},"documentSetId":{"type":"string"},"title":{"type":"string","example":"Brand Value Pillars & Messaging"},"slug":{"type":"string","example":"brand-value-pillars"},"sourceType":{"type":"string","enum":["markdown","text","pdf","docx","html","csv"]},"tags":{"type":"array","items":{"type":"string"},"example":["brand","seo","approved"]},"currentVersionId":{"type":"string","nullable":true},"status":{"type":"string","enum":["queued","normalizing","indexing","indexed","failed","deleted"]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"RetrievalRequest":{"type":"object","required":["query"],"properties":{"query":{"type":"string","example":"What core differentiators should we highlight for hybrid teams?"},"documentSetIds":{"type":"array","items":{"type":"string"},"description":"Optional array of category IDs to restrict search to. Leave empty to search all permitted sets.","example":["set_01a01ac5450b7385a5d3df441c0a3e88"]},"tags":{"type":"array","items":{"type":"string"},"description":"Optional tags that must match on documents","example":["approved","2025"]},"dateRange":{"type":"object","properties":{"modifiedAfter":{"type":"string","format":"date-time","example":"2025-01-01T00:00:00Z"},"modifiedBefore":{"type":"string","format":"date-time"},"createdAfter":{"type":"string","format":"date-time"},"createdBefore":{"type":"string","format":"date-time"}}},"topK":{"type":"integer","default":10,"minimum":1,"maximum":50,"example":5},"mode":{"type":"string","enum":["semantic","hybrid"],"default":"semantic"},"scoreThreshold":{"type":"number","minimum":0,"maximum":1,"example":0.2},"maxChunksPerDocument":{"type":"integer","default":3,"minimum":1,"maximum":10}}},"RetrievalSource":{"type":"object","properties":{"sourceId":{"type":"string","example":"src_01"},"documentId":{"type":"string"},"documentVersionId":{"type":"string"},"documentSetId":{"type":"string"},"title":{"type":"string"},"headingPath":{"type":"array","items":{"type":"string"},"example":["Positioning","Target Audience"]},"excerpt":{"type":"string","example":"Marketcast empowers enterprise marketing teams with grounded intelligence..."},"score":{"type":"number","example":0.892},"retrievalMethod":{"type":"string","example":"semantic"}}},"RetrievalResponse":{"type":"object","properties":{"query":{"type":"string"},"sources":{"type":"array","items":{"$ref":"#/components/schemas/RetrievalSource"}},"retrieval":{"type":"object","properties":{"knowledgeBaseId":{"type":"string"},"appliedDocumentSetIds":{"type":"array","items":{"type":"string"}},"mode":{"type":"string"},"topK":{"type":"integer"},"auditId":{"type":"string"}}}}}}},"paths":{"/v1/knowledge-bases":{"get":{"summary":"List Knowledge Bases","tags":["Knowledge Bases"],"parameters":[{"name":"includeArchived","in":"query","schema":{"type":"boolean","default":false}}],"responses":{"200":{"description":"List of knowledge bases","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/KnowledgeBase"}}}}}}}}},"post":{"summary":"Create Knowledge Base","tags":["Knowledge Bases"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name","slug"],"properties":{"name":{"type":"string","example":"Product Marketing & SEO"},"slug":{"type":"string","example":"product-marketing-seo"},"description":{"type":"string","example":"Knowledge repository for product features and SEO topics"}}}}}},"responses":{"201":{"description":"Created Knowledge Base","content":{"application/json":{"schema":{"$ref":"#/components/schemas/KnowledgeBase"}}}}}}},"/v1/knowledge-bases/{kbId}":{"get":{"summary":"Get Knowledge Base by ID","tags":["Knowledge Bases"],"parameters":[{"name":"kbId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Knowledge Base details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/KnowledgeBase"}}}}}}},"/v1/knowledge-bases/{kbId}/document-sets":{"get":{"summary":"List Categories (Document Sets)","tags":["Categories / Document Sets"],"parameters":[{"name":"kbId","in":"path","required":true,"schema":{"type":"string"}},{"name":"includeArchived","in":"query","schema":{"type":"boolean","default":false}}],"responses":{"200":{"description":"List of document sets in the knowledge base","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/DocumentSet"}}}}}}}}},"post":{"summary":"Create Category (Document Set)","tags":["Categories / Document Sets"],"parameters":[{"name":"kbId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name","slug"],"properties":{"name":{"type":"string","example":"Brand Strategy"},"slug":{"type":"string","example":"brand-strategy"},"description":{"type":"string"},"sortOrder":{"type":"integer","default":10}}}}}},"responses":{"201":{"description":"Created document set","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DocumentSet"}}}}}}},"/v1/knowledge-bases/{kbId}/documents":{"get":{"summary":"List Documents","tags":["Documents"],"parameters":[{"name":"kbId","in":"path","required":true,"schema":{"type":"string"}},{"name":"documentSetId","in":"query","schema":{"type":"string"},"description":"Filter by category ID"},{"name":"status","in":"query","schema":{"type":"string"}},{"name":"tags","in":"query","schema":{"type":"string"},"description":"Comma separated tags"},{"name":"limit","in":"query","schema":{"type":"integer","default":50}},{"name":"offset","in":"query","schema":{"type":"integer","default":0}}],"responses":{"200":{"description":"Paginated list of documents","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/Document"}},"total":{"type":"integer"}}}}}}}},"post":{"summary":"Create Document (JSON text or File Upload)","tags":["Documents"],"parameters":[{"name":"kbId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["title","documentSetId","content"],"properties":{"title":{"type":"string","example":"2025 B2B SEO Strategy"},"documentSetId":{"type":"string"},"tags":{"type":"array","items":{"type":"string"},"example":["seo","strategy"]},"content":{"type":"string","example":"# 2025 B2B SEO Strategy\n\n## Overview\nHigh-intent informational content..."},"sourceType":{"type":"string","enum":["markdown","text","html","csv"],"default":"markdown"}}}},"multipart/form-data":{"schema":{"type":"object","required":["documentSetId","file"],"properties":{"title":{"type":"string"},"documentSetId":{"type":"string"},"tags":{"type":"string","description":"JSON array string of tags, e.g. [\"brand\", \"v1\"]"},"file":{"type":"string","format":"binary","description":"Supports PDF, Word (.docx), Markdown, Text, HTML, CSV"}}}}}},"responses":{"201":{"description":"Document created and ingestion job queued"}}}},"/v1/knowledge-bases/{kbId}/documents/{docId}":{"get":{"summary":"Get Document Detail & Version History","tags":["Documents"],"parameters":[{"name":"kbId","in":"path","required":true,"schema":{"type":"string"}},{"name":"docId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Document metadata, version history, normalized preview, and chunk manifest"}}},"patch":{"summary":"Update Document / Upload New Revision","tags":["Documents"],"parameters":[{"name":"kbId","in":"path","required":true,"schema":{"type":"string"}},{"name":"docId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string"},"documentSetId":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"content":{"type":"string","description":"When provided, creates a new immutable version and indexes in background"}}}},"multipart/form-data":{"schema":{"type":"object","properties":{"title":{"type":"string"},"documentSetId":{"type":"string"},"tags":{"type":"string"},"file":{"type":"string","format":"binary"}}}}}},"responses":{"200":{"description":"Document updated"}}},"delete":{"summary":"Delete Document (Immediate Retrieval Exclusion)","tags":["Documents"],"parameters":[{"name":"kbId","in":"path","required":true,"schema":{"type":"string"}},{"name":"docId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Document soft-deleted and Qdrant purge scheduled"}}}},"/v1/knowledge-bases/{kbId}/documents/{docId}/source":{"get":{"summary":"Download Raw Source Document File","tags":["Documents"],"parameters":[{"name":"kbId","in":"path","required":true,"schema":{"type":"string"}},{"name":"docId","in":"path","required":true,"schema":{"type":"string"}},{"name":"version","in":"query","schema":{"type":"integer"},"description":"Optional version number (defaults to active version)"}],"responses":{"200":{"description":"Original file stream (PDF, DOCX, Markdown, etc.)","content":{"*/*":{"schema":{"type":"string","format":"binary"}}}}}}},"/v1/knowledge-bases/{kbId}/retrieve":{"post":{"summary":"Execute Filtered Vector Retrieval (Playground)","tags":["Retrieval & Playground"],"description":"\n**Interactive Vector Retrieval**\n\nExecutes dense or hybrid semantic search in Qdrant against the requested knowledge base.\nServer-side pre-filters (`document_status: published`, `is_active_version: true`, category IDs, date ranges, and tags) are strictly applied prior to nearest-neighbor search.\n        ","parameters":[{"name":"kbId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RetrievalRequest"}}}},"responses":{"200":{"description":"Ranked citation sources with score and applied filter metadata","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RetrievalResponse"}}}}}}},"/v1/jobs":{"get":{"summary":"List Ingestion Jobs","tags":["Ingestion Jobs"],"parameters":[{"name":"status","in":"query","schema":{"type":"string","enum":["queued","processing","completed","failed"]}},{"name":"limit","in":"query","schema":{"type":"integer","default":50}}],"responses":{"200":{"description":"List of background indexing jobs"}}}},"/v1/jobs/{jobId}/retry":{"post":{"summary":"Retry Failed Ingestion Job","tags":["Ingestion Jobs"],"parameters":[{"name":"jobId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Job re-queued for processing"}}}},"/healthz":{"get":{"summary":"Health Check Probe","tags":["System"],"responses":{"200":{"description":"Service is healthy"}}}}}}