{ "components": { "schemas": { "BulkUpsertIn": { "properties": { "documents": { "items": { "$ref": "#/components/schemas/DocumentIn" }, "title": "Documents", "type": "array" } }, "required": [ "documents" ], "title": "BulkUpsertIn", "type": "object" }, "DocumentIn": { "properties": { "content": { "title": "Content", "type": "string" }, "expires_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Expires At" }, "id": { "title": "Id", "type": "string" }, "metadata": { "additionalProperties": true, "title": "Metadata", "type": "object" }, "source": { "default": "", "title": "Source", "type": "string" }, "tags": { "items": { "type": "string" }, "title": "Tags", "type": "array" } }, "required": [ "id", "content" ], "title": "DocumentIn", "type": "object" }, "HTTPValidationError": { "properties": { "detail": { "items": { "$ref": "#/components/schemas/ValidationError" }, "title": "Detail", "type": "array" } }, "title": "HTTPValidationError", "type": "object" }, "QueryIn": { "properties": { "min_score": { "default": 0.0, "maximum": 1.0, "minimum": 0.0, "title": "Min Score", "type": "number" }, "strategy": { "default": "similarity", "title": "Strategy", "type": "string" }, "tags": { "default": "", "title": "Tags", "type": "string" }, "text": { "minLength": 1, "title": "Text", "type": "string" }, "top_k": { "default": 5, "maximum": 100.0, "minimum": 1.0, "title": "Top K", "type": "integer" } }, "required": [ "text" ], "title": "QueryIn", "type": "object" }, "SourceSnapshotIn": { "properties": { "documents": { "items": { "$ref": "#/components/schemas/DocumentIn" }, "title": "Documents", "type": "array" } }, "required": [ "documents" ], "title": "SourceSnapshotIn", "type": "object" }, "ValidationError": { "properties": { "ctx": { "title": "Context", "type": "object" }, "input": { "title": "Input" }, "loc": { "items": { "anyOf": [ { "type": "string" }, { "type": "integer" } ] }, "title": "Location", "type": "array" }, "msg": { "title": "Message", "type": "string" }, "type": { "title": "Error Type", "type": "string" } }, "required": [ "loc", "msg", "type" ], "title": "ValidationError", "type": "object" } }, "securitySchemes": { "MetricsToken": { "description": "The metrics token (METRICS_TOKEN)", "scheme": "bearer", "type": "http" }, "PluginToken": { "description": "The plugin's own token, spot_pt_...", "scheme": "bearer", "type": "http" } } }, "info": { "title": "SPOT Knowledge Store", "version": "2.1.0" }, "openapi": "3.1.0", "paths": { "/api/v1/knowledge/bulk-upsert": { "post": { "operationId": "bulk_upsert_api_v1_knowledge_bulk_upsert_post", "parameters": [ { "in": "header", "name": "X-Internal-API-Key", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Internal-Api-Key" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkUpsertIn" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "title": "Response Bulk Upsert Api V1 Knowledge Bulk Upsert Post", "type": "object" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "PluginToken": [] } ], "summary": "Bulk Upsert", "tags": [ "Knowledge Store" ] } }, "/api/v1/knowledge/debug/slow-queries": { "get": { "operationId": "slow_queries_api_v1_knowledge_debug_slow_queries_get", "parameters": [ { "in": "header", "name": "X-Internal-API-Key", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Internal-Api-Key" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "title": "Response Slow Queries Api V1 Knowledge Debug Slow Queries Get", "type": "object" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Slow Queries", "tags": [ "Knowledge Store", "Core only" ] } }, "/api/v1/knowledge/documents": { "get": { "operationId": "list_documents_api_v1_knowledge_documents_get", "parameters": [ { "in": "query", "name": "tags", "required": false, "schema": { "default": "", "title": "Tags", "type": "string" } }, { "in": "query", "name": "source", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Source" } }, { "in": "query", "name": "q", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Q" } }, { "in": "query", "name": "offset", "required": false, "schema": { "default": 0, "title": "Offset", "type": "integer" } }, { "in": "query", "name": "limit", "required": false, "schema": { "default": 50, "title": "Limit", "type": "integer" } }, { "in": "header", "name": "X-Internal-API-Key", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Internal-Api-Key" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "title": "Response List Documents Api V1 Knowledge Documents Get", "type": "object" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "PluginToken": [] } ], "summary": "List Documents", "tags": [ "Knowledge Store" ] } }, "/api/v1/knowledge/health": { "get": { "operationId": "health_api_v1_knowledge_health_get", "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": { "type": "string" }, "title": "Response Health Api V1 Knowledge Health Get", "type": "object" } } }, "description": "Successful Response" } }, "summary": "Health", "tags": [ "Knowledge Store" ] } }, "/api/v1/knowledge/query": { "post": { "operationId": "query_api_v1_knowledge_query_post", "parameters": [ { "in": "header", "name": "X-Internal-API-Key", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Internal-Api-Key" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueryIn" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "title": "Response Query Api V1 Knowledge Query Post", "type": "object" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "PluginToken": [] } ], "summary": "Query", "tags": [ "Knowledge Store" ] } }, "/api/v1/knowledge/sources": { "get": { "operationId": "sources_api_v1_knowledge_sources_get", "parameters": [ { "in": "header", "name": "X-Internal-API-Key", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Internal-Api-Key" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "title": "Response Sources Api V1 Knowledge Sources Get", "type": "object" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "PluginToken": [] } ], "summary": "Sources", "tags": [ "Knowledge Store" ] } }, "/api/v1/knowledge/sources/{source}/documents": { "put": { "description": "Replace the source's documents with the snapshot sent, in one transaction.\n\nOnly the provider whose id is the source may: core and any other\nplugin are refused. A document unchanged since the last sync (content,\ntags, metadata and expiry, under the same embedding model) is left as it\nis: ``upserted`` counts the documents written, the changed and the new,\nnot the snapshot's, and ``deleted`` those of the source it no longer holds.", "operationId": "replace_source_api_v1_knowledge_sources__source__documents_put", "parameters": [ { "in": "path", "name": "source", "required": true, "schema": { "title": "Source", "type": "string" } }, { "in": "header", "name": "X-Internal-API-Key", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Internal-Api-Key" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SourceSnapshotIn" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "title": "Response Replace Source Api V1 Knowledge Sources Source Documents Put", "type": "object" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "PluginToken": [] } ], "summary": "Replace Source", "tags": [ "Knowledge Store" ] } }, "/api/v1/knowledge/sources/{source}/documents/{doc_id}": { "delete": { "description": "Delete one document of the source; a plugin, only one of its own.", "operationId": "delete_api_v1_knowledge_sources__source__documents__doc_id__delete", "parameters": [ { "in": "path", "name": "source", "required": true, "schema": { "title": "Source", "type": "string" } }, { "in": "path", "name": "doc_id", "required": true, "schema": { "title": "Doc Id", "type": "string" } }, { "in": "header", "name": "X-Internal-API-Key", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Internal-Api-Key" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "title": "Response Delete Api V1 Knowledge Sources Source Documents Doc Id Delete", "type": "object" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "PluginToken": [] } ], "summary": "Delete", "tags": [ "Knowledge Store" ] }, "get": { "operationId": "get_document_api_v1_knowledge_sources__source__documents__doc_id__get", "parameters": [ { "in": "path", "name": "source", "required": true, "schema": { "title": "Source", "type": "string" } }, { "in": "path", "name": "doc_id", "required": true, "schema": { "title": "Doc Id", "type": "string" } }, { "in": "header", "name": "X-Internal-API-Key", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Internal-Api-Key" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "title": "Response Get Document Api V1 Knowledge Sources Source Documents Doc Id Get", "type": "object" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "PluginToken": [] } ], "summary": "Get Document", "tags": [ "Knowledge Store" ] } }, "/api/v1/knowledge/stats": { "get": { "operationId": "stats_api_v1_knowledge_stats_get", "parameters": [ { "in": "header", "name": "X-Internal-API-Key", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Internal-Api-Key" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "title": "Response Stats Api V1 Knowledge Stats Get", "type": "object" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "PluginToken": [] } ], "summary": "Stats", "tags": [ "Knowledge Store" ] } }, "/api/v1/knowledge/upsert": { "post": { "operationId": "upsert_api_v1_knowledge_upsert_post", "parameters": [ { "in": "header", "name": "X-Internal-API-Key", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Internal-Api-Key" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentIn" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "title": "Response Upsert Api V1 Knowledge Upsert Post", "type": "object" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "PluginToken": [] } ], "summary": "Upsert", "tags": [ "Knowledge Store" ] } }, "/health": { "get": { "description": "Liveness + dependency snapshot.\n\nSame shape as api-gateway / analyzer-orchestrator / mail-orchestrator\nso the dashboard's services rollup can render it uniformly.\nAlways returns 200: this endpoint reports liveness; the richer\n``/readiness`` is what callers should gate workload routing on.", "operationId": "root_health_health_get", "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "title": "Response Root Health Health Get", "type": "object" } } }, "description": "Successful Response" } }, "summary": "Root Health", "tags": [ "Core only" ] } }, "/metrics": { "get": { "operationId": "metrics_metrics_get", "responses": { "200": { "content": { "text/plain": {} }, "description": "Prometheus text format" }, "401": { "description": "Without the metrics token" }, "503": { "description": "Metrics are off: METRICS_TOKEN is not set" } }, "security": [ { "MetricsToken": [] } ], "summary": "Metrics", "tags": [ "Metrics" ] } }, "/readiness": { "get": { "operationId": "root_readiness_readiness_get", "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "title": "Response Root Readiness Readiness Get", "type": "object" } } }, "description": "Successful Response" } }, "summary": "Root Readiness", "tags": [ "Core only" ] } } }, "tags": [ { "description": "Called by SPOT's own services only", "name": "Core only" } ] }