openapi.json

{
  "openapi": "3.1.0",
  "info": {
    "title": "KB Brain API",
    "version": "1.0.0",
    "description": "Knowledge Base Brain API. Use this API to search, read, and ingest documents from the personal knowledge base. When you need to find information about projects, architecture, configurations, debugging sessions, or any accumulated knowledge, use the search and context endpoints. Use ingest and capture endpoints to record new knowledge, bug fixes, or research."
  },
  "servers": [
    {
      "url": "https://brain.cutdacord.app",
      "description": "Production Brain API"
    },
    {
      "url": "http://localhost:3838",
      "description": "Local development"
    }
  ],
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "components": {
    "securitySchemes": {
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "API key as Bearer token. Use your KB_API_KEY_OPENAI value."
      },
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key",
        "description": "Alternative: API key via X-API-Key header"
      }
    },
    "schemas": {
      "SearchResult": {
        "type": "object",
        "properties": {
          "id": { "type": "integer", "description": "Unique document identifier" },
          "title": { "type": "string", "description": "Document title" },
          "snippet": { "type": "string", "description": "Relevant excerpt from the document matching the search query" },
          "doc_type": { "type": "string", "description": "Document type (e.g. note, tutorial, bookmark, config, debug-session, fix-pattern, web-article)" },
          "tags": { "type": "array", "items": { "type": "string" }, "description": "Tags associated with the document" },
          "file_size": { "type": "integer", "description": "Document size in bytes" },
          "created_at": { "type": "string", "format": "date-time", "description": "Document creation timestamp" },
          "rank": { "type": "number", "description": "Search relevance rank score" }
        }
      },
      "Document": {
        "type": "object",
        "properties": {
          "id": { "type": "integer" },
          "title": { "type": "string" },
          "content": { "type": "string", "description": "Full document content" },
          "source": { "type": "string", "description": "Origin source URL or path" },
          "doc_type": { "type": "string" },
          "tags": { "type": "array", "items": { "type": "string" } },
          "file_path": { "type": "string", "description": "Path to source file if applicable" },
          "file_size": { "type": "integer" },
          "created_at": { "type": "string", "format": "date-time" },
          "updated_at": { "type": "string", "format": "date-time" }
        }
      },
      "CaptureResponse": {
        "type": "object",
        "properties": {
          "id": { "type": "integer" },
          "title": { "type": "string" },
          "vault_path": { "type": "string", "description": "Path in the Obsidian vault where the document was saved" },
          "created_at": { "type": "string", "format": "date-time" }
        }
      },
      "Error": {
        "type": "object",
        "properties": {
          "error": { "type": "string", "description": "Error message" }
        }
      }
    }
  },
  "paths": {
    "/api/v1/health": {
      "get": {
        "operationId": "healthCheck",
        "summary": "Health check",
        "description": "Check if the KB Brain API is running and healthy. No authentication required. Returns status and uptime.",
        "security": [],
        "responses": {
          "200": {
            "description": "Service is healthy",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": { "type": "string", "example": "ok" },
                    "uptime": { "type": "number", "description": "Server uptime in seconds" }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/stats": {
      "get": {
        "operationId": "getStats",
        "summary": "Knowledge base statistics",
        "description": "Returns aggregate statistics about the knowledge base: total document count, total content size, and database size. Useful for understanding the scope of the knowledge base.",
        "responses": {
          "200": {
            "description": "KB statistics",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "total_documents": { "type": "integer", "description": "Total number of documents in the KB" },
                    "total_size_bytes": { "type": "integer", "description": "Total size of all document content in bytes" },
                    "db_size_bytes": { "type": "integer", "description": "Total PostgreSQL database size in bytes" }
                  }
                }
              }
            }
          },
          "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }
        }
      }
    },
    "/api/v1/search": {
      "get": {
        "operationId": "search",
        "summary": "Full-text search",
        "description": "Search the knowledge base using PostgreSQL full-text search. Use this to find documents, notes, tutorials, bookmarks, or any indexed content. The query supports natural language. Use the type parameter to narrow results to a specific document category. Results are ranked by relevance.",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "required": true,
            "description": "Search query string. Supports natural language and keyword combinations.",
            "schema": { "type": "string" }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Maximum number of results to return. Defaults to 10, max 50.",
            "schema": { "type": "integer", "default": 10, "maximum": 50 }
          },
          {
            "name": "type",
            "in": "query",
            "required": false,
            "description": "Filter by document type (e.g. note, tutorial, bookmark, config, debug-session, fix-pattern, web-article).",
            "schema": { "type": "string" }
          },
          {
            "name": "project",
            "in": "query",
            "required": false,
            "description": "Filter results by project name or tag.",
            "schema": { "type": "string" }
          }
        ],
        "responses": {
          "200": {
            "description": "Search results ranked by relevance",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "results": {
                      "type": "array",
                      "items": { "$ref": "#/components/schemas/SearchResult" }
                    }
                  }
                }
              }
            }
          },
          "400": { "description": "Missing required query parameter q", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
          "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }
        }
      }
    },
    "/api/v1/search/smart": {
      "get": {
        "operationId": "smartSearch",
        "summary": "Hybrid semantic + full-text search",
        "description": "Advanced search combining full-text search with semantic/vector similarity. Use this when a regular search returns poor results or when you need conceptually related documents even if they don't share exact keywords. Better for finding information about a topic expressed in different terms.",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "required": true,
            "description": "Search query. Supports natural language, concepts, and keywords.",
            "schema": { "type": "string" }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Maximum number of results to return. Defaults to 10.",
            "schema": { "type": "integer", "default": 10 }
          },
          {
            "name": "type",
            "in": "query",
            "required": false,
            "description": "Filter by document type.",
            "schema": { "type": "string" }
          },
          {
            "name": "project",
            "in": "query",
            "required": false,
            "description": "Filter by project.",
            "schema": { "type": "string" }
          }
        ],
        "responses": {
          "200": {
            "description": "Semantically ranked search results",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "results": {
                      "type": "array",
                      "items": { "$ref": "#/components/schemas/SearchResult" }
                    }
                  }
                }
              }
            }
          },
          "400": { "description": "Missing required query parameter q", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
          "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }
        }
      }
    },
    "/api/v1/context": {
      "get": {
        "operationId": "getContext",
        "summary": "Token-efficient knowledge briefing",
        "description": "Returns a synthesized briefing on a topic for LLM consumption. Returns a narrative summary with source citations instead of raw documents. Use to quickly understand a topic without reading full documents.",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "required": true,
            "description": "Topic or question to generate a briefing for.",
            "schema": { "type": "string" }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Maximum number of source documents to include in briefing. Defaults to 5.",
            "schema": { "type": "integer", "default": 5 }
          }
        ],
        "responses": {
          "200": {
            "description": "Synthesized briefing with source citations",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "briefing": { "type": "string", "description": "Synthesized narrative briefing on the topic" },
                    "sources": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": { "type": "integer" },
                          "title": { "type": "string" }
                        }
                      },
                      "description": "Source documents used to generate the briefing"
                    }
                  }
                }
              }
            }
          },
          "400": { "description": "Missing required query parameter q", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
          "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }
        }
      }
    },
    "/api/v1/documents": {
      "get": {
        "operationId": "listDocuments",
        "summary": "List documents",
        "description": "Browse and paginate through all documents in the knowledge base. Filter by document type or tag to narrow results. Useful for exploring what's available or listing all documents of a specific category.",
        "parameters": [
          {
            "name": "type",
            "in": "query",
            "required": false,
            "description": "Filter by document type (e.g. note, tutorial, bookmark, config, debug-session, fix-pattern, web-article).",
            "schema": { "type": "string" }
          },
          {
            "name": "tag",
            "in": "query",
            "required": false,
            "description": "Filter by a specific tag.",
            "schema": { "type": "string" }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Number of documents per page. Defaults to 20, max 100.",
            "schema": { "type": "integer", "default": 20, "maximum": 100 }
          },
          {
            "name": "offset",
            "in": "query",
            "required": false,
            "description": "Number of documents to skip for pagination. Defaults to 0.",
            "schema": { "type": "integer", "default": 0 }
          }
        ],
        "responses": {
          "200": {
            "description": "Paginated list of documents",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "documents": {
                      "type": "array",
                      "items": { "$ref": "#/components/schemas/Document" }
                    },
                    "total": { "type": "integer", "description": "Total number of documents matching the filters" }
                  }
                }
              }
            }
          },
          "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }
        }
      }
    },
    "/api/v1/documents/{id}": {
      "get": {
        "operationId": "getDocument",
        "summary": "Read full document",
        "description": "Retrieve the complete content of a specific document by its ID. Use this after a search to read the full text of a result. Returns all metadata and the complete document content.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Document ID as returned by search or list endpoints.",
            "schema": { "type": "integer" }
          }
        ],
        "responses": {
          "200": {
            "description": "Full document with content and metadata",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Document" }
              }
            }
          },
          "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
          "404": { "description": "Document not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }
        }
      }
    },
    "/api/v1/ingest": {
      "post": {
        "operationId": "ingestDocument",
        "summary": "Ingest text content into the knowledge base",
        "description": "Add a new document to the knowledge base by providing text content directly. Use this to store notes, summaries, research findings, or any text that should be searchable later. The document will be indexed for full-text and semantic search immediately.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["title", "content"],
                "properties": {
                  "title": { "type": "string", "description": "Document title" },
                  "content": { "type": "string", "description": "Full text content to ingest" },
                  "doc_type": { "type": "string", "description": "Document type classification (e.g. note, research, summary)", "default": "note" },
                  "tags": { "type": "array", "items": { "type": "string" }, "description": "Tags for categorization and filtering" },
                  "source": { "type": "string", "description": "Source URL or reference for the content" }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Document successfully ingested",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "id": { "type": "integer" },
                    "title": { "type": "string" },
                    "created_at": { "type": "string", "format": "date-time" }
                  }
                }
              }
            }
          },
          "400": { "description": "Missing required fields title or content", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
          "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }
        }
      }
    },
    "/api/v1/capture/session": {
      "post": {
        "operationId": "captureSession",
        "summary": "Record a debugging session",
        "description": "Capture and store a debugging session for future reference. Use this to record what happened during a troubleshooting session: the problem, steps taken, commands run, and resolution. Stored as a structured debug-session document for later retrieval.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["title", "problem", "resolution"],
                "properties": {
                  "title": { "type": "string", "description": "Brief title describing the issue" },
                  "problem": { "type": "string", "description": "Description of the problem encountered" },
                  "steps": { "type": "array", "items": { "type": "string" }, "description": "Ordered list of debugging steps taken" },
                  "resolution": { "type": "string", "description": "How the problem was resolved" },
                  "tags": { "type": "array", "items": { "type": "string" }, "description": "Tags for categorization (e.g. project name, technology)" },
                  "commands": { "type": "array", "items": { "type": "string" }, "description": "Key commands or code snippets used during debugging" }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Debugging session recorded",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/CaptureResponse" }
              }
            }
          },
          "400": { "description": "Missing required fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
          "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }
        }
      }
    },
    "/api/v1/capture/fix": {
      "post": {
        "operationId": "captureFix",
        "summary": "Record a bug fix pattern",
        "description": "Store a bug fix as a reusable pattern. Use this when you fix a bug that could recur, to capture the root cause, fix approach, and prevention strategy. These patterns are indexed as fix-pattern documents and help avoid repeating the same mistakes.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["title", "bug", "fix"],
                "properties": {
                  "title": { "type": "string", "description": "Concise title for the fix pattern" },
                  "bug": { "type": "string", "description": "Description of the bug and its symptoms" },
                  "root_cause": { "type": "string", "description": "Root cause of the bug" },
                  "fix": { "type": "string", "description": "The fix applied and why it works" },
                  "prevention": { "type": "string", "description": "How to prevent this class of bug in the future" },
                  "tags": { "type": "array", "items": { "type": "string" }, "description": "Tags for categorization" },
                  "code_before": { "type": "string", "description": "Code snippet before the fix" },
                  "code_after": { "type": "string", "description": "Code snippet after the fix" }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Fix pattern recorded",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/CaptureResponse" }
              }
            }
          },
          "400": { "description": "Missing required fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
          "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }
        }
      }
    },
    "/api/v1/capture/web": {
      "post": {
        "operationId": "captureWeb",
        "summary": "Capture and store a web article",
        "description": "Fetch and ingest a web article or page into the knowledge base by URL. The content will be extracted, cleaned, and stored as a web-article document for future search and retrieval. Use this to save useful blog posts, documentation pages, or any online resource.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["url"],
                "properties": {
                  "url": { "type": "string", "format": "uri", "description": "URL of the web page to capture" },
                  "tags": { "type": "array", "items": { "type": "string" }, "description": "Tags to apply to the captured document" },
                  "title_override": { "type": "string", "description": "Optional custom title to use instead of the page title" }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Web article captured and ingested",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/CaptureResponse" }
              }
            }
          },
          "400": { "description": "Missing required field url or invalid URL", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
          "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
          "422": { "description": "Failed to fetch or parse the web page", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }
        }
      }
    }
  }
}