{
  "openapi": "3.1.0",
  "info": {
    "title": "Sol Knowledge API",
    "version": "1.0.0",
    "description": "Read-only semantic search over Sol's public memory cache using the existing Sol/MasterBot embedding pipeline. Repeated identical queries reuse a backend-specific server-side query-embedding cache."
  },
  "servers": [
    {
      "url": "https://sol.system42.one"
    }
  ],
  "paths": {
    "/api/knowledge/query": {
      "get": {
        "operationId": "queryKnowledge",
        "summary": "Semantic search over the knowledge cache",
        "parameters": [
          {
            "name": "query",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Natural-language query text."
          },
          {
            "name": "top_k",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "default": 5,
              "minimum": 1,
              "maximum": 12
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Top matching knowledge chunks",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "query": {
                      "type": "string"
                    },
                    "top_k": {
                      "type": "integer"
                    },
                    "backend": {
                      "type": "string"
                    },
                    "cache_path": {
                      "type": "string"
                    },
                    "requested_backend": {
                      "type": "string"
                    },
                    "warning": {
                      "type": "string"
                    },
                    "results": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "rank": {
                            "type": "integer"
                          },
                          "score": {
                            "type": "number"
                          },
                          "path": {
                            "type": "string"
                          },
                          "chunk": {
                            "type": "integer"
                          },
                          "doc_key": {
                            "type": "string"
                          },
                          "text": {
                            "type": "string"
                          }
                        },
                        "required": [
                          "rank",
                          "score",
                          "path",
                          "chunk",
                          "doc_key",
                          "text"
                        ]
                      }
                    }
                  },
                  "required": [
                    "query",
                    "top_k",
                    "backend",
                    "cache_path",
                    "results"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/api/knowledge/health": {
      "get": {
        "operationId": "knowledgeHealth",
        "summary": "Check whether the knowledge cache is loaded",
        "responses": {
          "200": {
            "description": "Current cache status, including query-embedding cache metadata when available",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean"
                    },
                    "backend": {
                      "type": "string"
                    },
                    "cache_path": {
                      "type": "string"
                    },
                    "knowledge_dir": {
                      "type": "string"
                    },
                    "docs": {
                      "type": "integer"
                    },
                    "query_cache_path": {
                      "type": "string"
                    },
                    "query_cache_entries": {
                      "type": "integer"
                    }
                  },
                  "required": [
                    "ok",
                    "backend",
                    "cache_path",
                    "knowledge_dir",
                    "docs",
                    "query_cache_path",
                    "query_cache_entries"
                  ]
                }
              }
            }
          }
        }
      }
    }
  }
}