{ "openapi": "3.1.0", "info": { "title": "ValorBrain Engine API", "description": "REST interface for ValorBrain's memory engine — search, retrieval, document lifecycle, RAG chat, knowledge graph, and multi-tenant management.\n", "version": "0.2.0", "contact": { "name": "Valor Digital", "url": "https://valor.digital" }, "license": { "name": "Proprietary" }, "x-valorbrain-generated-at": "2026-09-25T19:16:23.544Z", "x-valorbrain-public-url": "https://valorbrain-api.valor.digital", "x-valorbrain-yaml-operations": 144, "x-valorbrain-live-operations": 231, "x-valorbrain-missing-from-yaml": [ "GET /openapi.yaml", "GET /health/admin", "GET /reports/usage", "GET /api/v1/memory/team-activity", "GET /dashboard", "GET /memory-map", "GET /api/v1/knowledge-gaps", "POST /api/v1/knowledge-gaps/{id}/resolve", "POST /conversations", "GET /harness-coverage", "GET /contradictions", "GET /documents/changes", "GET /documents/{id}/chain", "PATCH /documents/{id}/veracity", "PATCH /api/v1/documents/{id}/veracity", "PATCH /documents/veracity/bulk", "PATCH /api/v1/documents/veracity/bulk", "GET /collections/health", "POST /collections/{id}/lifecycle", "GET /api/v1/memory/working-context", "GET /memory/working-context", "GET /api/v1/scratchpad", "PUT /api/v1/scratchpad", "POST /api/v1/scratchpad", "DELETE /api/v1/scratchpad", "GET /scratchpad", "PUT /scratchpad", "POST /scratchpad", "DELETE /scratchpad", "GET /setup/artifacts", "GET /api/v1/entity-cards", "POST /api/v1/feedback", "GET /api/v1/secrets", "POST /api/v1/secrets", "PATCH /api/v1/entities/{name}/card", "DELETE /api/v1/entities/{name}/card", "GET /api/v1/pins", "POST /api/v1/pins", "GET /api/v1/pins/{id}", "PATCH /api/v1/pins/{id}", "DELETE /api/v1/pins/{id}", "POST /api/v1/session-handoffs", "GET /api/v1/session-handoffs", "GET /api/v1/team/members", "GET /api/v1/team/overview", "GET /api/v1/task-state", "POST /api/v1/team/messages", "GET /api/v1/team/inbox", "POST /api/v1/team/handoffs", "GET /api/v1/team/handoffs", "GET /api/v1/team/briefing", "GET /api/v1/team/stream", "GET /api/v1/memory/episodes", "GET /api/v1/memory/episodes/{id}", "GET /admin/queues", "POST /admin/queues", "POST /api/v1/admin/tenants/{id}/api-tokens", "GET /api/v1/admin/tenants/{id}/api-tokens", "DELETE /api/v1/admin/tenants/{id}/api-tokens/{id2}", "PATCH /api/v1/admin/tenants/{id}/status", "POST /api/v1/memory/refine", "POST /api/v1/runtimes/register", "POST /api/v1/runtimes/heartbeat", "GET /api/v1/runtimes", "GET /api/v1/kg/explore", "GET /api/v1/kg/entity-documents", "POST /api/v1/memory/store", "GET /api/v1/memory/confirm-sample", "GET /api/v1/tenant/trust-summary", "GET /api/v1/tenant/perf-summary", "GET /api/v1/tenant/impact", "POST /api/v1/users/resolve-caller", "GET /api/v1/users/channel-identities", "POST /api/v1/users/channel-identities", "GET /api/v1/audit/pubkey", "GET /api/v1/audit/bundle", "GET /api/v1/audit/status", "GET /api/v1/audit/recent", "GET /api/v1/read-log/summary", "GET /api/v1/lessons", "POST /api/v1/lessons/record", "POST /api/v1/lessons/feedback", "GET /api/v1/arcs", "POST /api/v1/arcs", "GET /api/v1/keyed-facts/as-of", "POST /api/v1/keyed-facts", "POST /api/v1/keyed-facts/correct", "POST /api/v1/authority/mandates", "GET /api/v1/authority/mandates", "POST /api/v1/harness-integrations", "GET /api/v1/harness-integrations", "POST /api/v1/memory/prepare", "GET /api/v1/kg/quarantine", "GET /api/v1/kg/entity-resolve/report", "POST /api/v1/kg/rag-retrieve", "GET /api/v1/usage/answers", "GET /api/v1/credits/summary", "POST /api/v1/session-bootstrap", "POST /api/v1/hooks/run", "POST /api/v1/decisions", "POST /api/v1/decisions/relations", "GET /api/v1/decisions/chain", "GET /api/v1/decisions/similar", "GET /api/v1/decisions/impact", "GET /api/v1/decisions", "POST /api/v1/provenance", "GET /api/v1/provenance/lineage", "GET /api/v1/provenance/export", "GET /api/v1/provenance/verify", "POST /api/v1/conflicts/detect", "GET /api/v1/fact-conflicts", "POST /api/v1/conflicts/resolve", "GET /api/v1/contradictions", "POST /api/v1/contradictions/{n}/resolve" ] }, "servers": [ { "url": "https://valorbrain-api.valor.digital", "description": "Hosted engine REST" }, { "url": "http://localhost:7438", "description": "Local engine (self-hosted)" } ], "security": [ { "bearerAuth": [] } ], "tags": [ { "name": "Health", "description": "Liveness, readiness, and system diagnostics" }, { "name": "Documents", "description": "Document CRUD, ingest, and mutations" }, { "name": "Search", "description": "Hybrid search, temporal, hierarchical, and retrieve" }, { "name": "Ask", "description": "RAG chat with LLM answer and source citations" }, { "name": "Graph", "description": "Causal links, similarity, and memory evolution" }, { "name": "Entity", "description": "Entity cards and SPO triples" }, { "name": "Foundations", "description": "Knowledge OS Tier-0 context and foundation management" }, { "name": "Agents", "description": "Agent signup, identify, claim, and verify" }, { "name": "Workspace", "description": "Cross-agent workspace: focus, sessions, handoffs" }, { "name": "Users", "description": "User management" }, { "name": "Identity", "description": "Agent/user identity profile" }, { "name": "Billing", "description": "Credits, pricing, subscriptions, and plans" }, { "name": "Admin", "description": "Tenant management, error logging (requires ENGINE_ADMIN_SECRET)" }, { "name": "OAuth", "description": "OAuth 2.1 authorization server and protected resource" }, { "name": "MCP Tokens", "description": "MCP API token CRUD" }, { "name": "Observability", "description": "Metrics, traces, ROI, and feature flags" }, { "name": "Canonical", "description": "Canonical tracking, conflicts, proposals, and probes" }, { "name": "Lifecycle", "description": "Document lifecycle: status, sweep, restore" }, { "name": "Maintenance", "description": "Reindex, graph build, and collection settings" } ], "paths": { "/healthz": { "get": { "operationId": "healthz", "summary": "Public liveness probe", "description": "Returns 200 if the process is up. No auth, no store dependency.", "tags": [ "Health" ], "security": [], "responses": { "200": { "description": "Process is alive", "content": { "application/json": { "schema": { "type": "object", "required": [ "status", "service", "timestamp" ], "properties": { "status": { "type": "string", "enum": [ "ok" ] }, "service": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" } } } } } } } } }, "/health": { "get": { "operationId": "health", "summary": "Health check with database status", "description": "Returns service status, document counts, vector index state, and request context.", "tags": [ "Health" ], "security": [], "responses": { "200": { "description": "Service health", "content": { "application/json": { "schema": { "type": "object", "required": [ "status", "service" ], "properties": { "status": { "type": "string" }, "service": { "type": "string" }, "version": { "type": "string" }, "database": { "type": "string" }, "documents": { "type": "integer" }, "needsEmbedding": { "type": "integer" }, "hasVectors": { "type": "boolean" }, "request": { "$ref": "#/components/schemas/RequestContext" } } } } } } } } }, "/health/deep": { "get": { "operationId": "healthDeep", "summary": "Deep health check with per-component probes", "description": "Probes database, documents, LLM config, and embed worker. Used by uptime monitors.", "tags": [ "Health" ], "security": [], "responses": { "200": { "description": "Component-level health", "content": { "application/json": { "schema": { "type": "object", "required": [ "checks" ], "properties": { "checks": { "type": "object", "additionalProperties": { "type": "object", "required": [ "ok" ], "properties": { "ok": { "type": "boolean" }, "latency_ms": { "type": "integer" }, "detail": { "type": "string" }, "error": { "type": "string" } } } }, "latency_ms": { "type": "integer" } } } } } } } } }, "/state": { "get": { "operationId": "state", "summary": "Engine state summary", "tags": [ "Health" ], "responses": { "200": { "description": "State object", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/stats": { "get": { "operationId": "stats", "summary": "Index statistics and health", "tags": [ "Health" ], "responses": { "200": { "description": "Stats including document counts, collections, and health", "content": { "application/json": { "schema": { "type": "object", "properties": { "documents": { "type": "integer" }, "totalDocuments": { "type": "integer" }, "needsEmbedding": { "type": "integer" }, "collections": { "type": "array", "items": { "type": "object" } }, "health": { "type": "object" } } } } } } } } }, "/reports/memory": { "get": { "operationId": "reportsMemory", "summary": "Memory usage report", "description": "Tenant-scoped memory report. Requires X-Tenant-ID.", "tags": [ "Health" ], "parameters": [ { "$ref": "#/components/parameters/TenantIdHeader" } ], "responses": { "200": { "description": "Memory report", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/BadRequest" } } } }, "/documents": { "post": { "operationId": "ingestDocument", "summary": "Ingest a document", "description": "Create or update a document in a collection. Supports quality gate evaluation, schema packs, auto-linking, and temporal metadata. Requires X-Tenant-ID.\n", "tags": [ "Documents" ], "parameters": [ { "$ref": "#/components/parameters/TenantIdHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "collection", "path", "content" ], "properties": { "collection": { "type": "string", "description": "Collection name" }, "path": { "type": "string", "description": "Unique document path within the collection" }, "title": { "type": "string" }, "content": { "type": "string", "maxLength": 1000000, "description": "Document body (max 1MB)" }, "content_type": { "type": "string", "default": "note" }, "confidence": { "type": "number", "minimum": 0, "maximum": 1, "default": 0.5 }, "quality_score": { "type": "number", "minimum": 0, "maximum": 1, "default": 0.5 }, "metadata": { "type": "object", "additionalProperties": true }, "user_id": { "type": "string" }, "run_id": { "type": "string" }, "event_at": { "type": "string", "format": "date-time" }, "event_type": { "type": "string" } } } } } }, "responses": { "200": { "description": "Document ingested", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "id": { "type": "integer" }, "path": { "type": "string" }, "hash": { "type": "string" }, "embed_state": { "type": "string" }, "gate_verdict": { "type": "object", "properties": { "shouldIndex": { "type": "boolean" }, "reason": { "type": "string" } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" } } }, "get": { "operationId": "listDocuments", "summary": "List documents", "description": "List documents with optional filtering by collection.", "tags": [ "Documents" ], "parameters": [ { "$ref": "#/components/parameters/TenantIdHeader" }, { "name": "collection", "in": "query", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "default": 0 } } ], "responses": { "200": { "description": "List of documents", "content": { "application/json": { "schema": { "type": "object", "properties": { "documents": { "type": "array", "items": { "$ref": "#/components/schemas/Document" } }, "total": { "type": "integer" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/documents/{id}": { "get": { "operationId": "getDocument", "summary": "Get a document by ID or hash", "tags": [ "Documents" ], "parameters": [ { "$ref": "#/components/parameters/TenantIdHeader" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Document ID or hash" } ], "responses": { "200": { "description": "Document details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Document" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/documents/{id}/visibility": { "patch": { "operationId": "patchDocumentVisibility", "summary": "Update document visibility", "tags": [ "Documents" ], "parameters": [ { "$ref": "#/components/parameters/TenantIdHeader" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "visibility" ], "properties": { "visibility": { "type": "string" } } } } } }, "responses": { "200": { "description": "Visibility updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/documents/{id}/pin": { "post": { "operationId": "pinDocument", "summary": "Pin a document for permanent prioritization", "tags": [ "Documents" ], "parameters": [ { "$ref": "#/components/parameters/TenantIdHeader" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Document pinned", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/documents/{id}/snooze": { "post": { "operationId": "snoozeDocument", "summary": "Temporarily hide a document from context", "tags": [ "Documents" ], "parameters": [ { "$ref": "#/components/parameters/TenantIdHeader" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "until": { "type": "string", "format": "date-time" } } } } } }, "responses": { "200": { "description": "Document snoozed", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/documents/{id}/forget": { "post": { "operationId": "forgetDocument", "summary": "Permanently deactivate a document", "tags": [ "Documents" ], "parameters": [ { "$ref": "#/components/parameters/TenantIdHeader" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Document forgotten", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/documents/{id}/feedback": { "post": { "operationId": "documentFeedback", "summary": "Submit relevance feedback for a document", "tags": [ "Documents" ], "parameters": [ { "$ref": "#/components/parameters/TenantIdHeader" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "relevance" ], "properties": { "relevance": { "type": "string", "enum": [ "positive", "negative" ] } } } } } }, "responses": { "200": { "description": "Feedback recorded", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/documents/purge": { "delete": { "operationId": "purgeDocuments", "summary": "Purge documents by collection", "description": "Delete all documents in a collection (exact or prefix match). Cleans up vectors, triples, and orphan records. Requires X-Tenant-ID.\n", "tags": [ "Documents" ], "parameters": [ { "$ref": "#/components/parameters/TenantIdHeader" }, { "name": "collection", "in": "query", "schema": { "type": "string" }, "description": "Exact collection name" }, { "name": "collection_prefix", "in": "query", "schema": { "type": "string" }, "description": "Collection name prefix (LIKE match)" } ], "responses": { "200": { "description": "Purge result", "content": { "application/json": { "schema": { "type": "object", "properties": { "purged": { "type": "integer" }, "orphan_vectors_cleaned": { "type": "integer" }, "orphan_triples_cleaned": { "type": "integer" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/api/v1/documents/{id}/canonical": { "post": { "operationId": "setCanonical", "summary": "Mark a document as canonical", "tags": [ "Canonical" ], "parameters": [ { "$ref": "#/components/parameters/TenantIdHeader" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "canonical": { "type": "boolean" } } } } } }, "responses": { "200": { "description": "Canonical status set", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/api/v1/documents/{id}/suggest-filters": { "post": { "operationId": "suggestFilters", "summary": "Suggest retrieval filters for a document", "tags": [ "Canonical" ], "parameters": [ { "$ref": "#/components/parameters/TenantIdHeader" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Suggested filters", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/api/v1/documents/{id}/probes": { "post": { "operationId": "registerProbe", "summary": "Register a validation probe for a document", "tags": [ "Canonical" ], "parameters": [ { "$ref": "#/components/parameters/TenantIdHeader" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Probe registered", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/search": { "post": { "operationId": "search", "summary": "Hybrid search (BM25 + vector + rerank)", "description": "Full hybrid search with optional HyDE expansion, self-correct retrieval, MMR diversity, and personalized graph ranking.\n", "tags": [ "Search" ], "parameters": [ { "$ref": "#/components/parameters/TenantIdHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "q" ], "properties": { "q": { "type": "string", "description": "Search query" }, "collection": { "type": "string", "description": "Filter to collection" }, "limit": { "type": "integer", "default": 10 }, "offset": { "type": "integer", "default": 0 }, "expand": { "type": "boolean", "description": "Force HyDE expansion on/off" }, "mode": { "type": "string", "enum": [ "auto", "keyword", "semantic", "causal", "hybrid" ] }, "diverse": { "type": "boolean", "default": true, "description": "Apply MMR diversity filter" } } } } } }, "responses": { "200": { "description": "Search results", "content": { "application/json": { "schema": { "type": "object", "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/SearchResult" } }, "query": { "type": "string" }, "mode": { "type": "string" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/search/temporal": { "post": { "operationId": "temporalSearch", "summary": "Temporal search with time-aware filtering", "tags": [ "Search" ], "parameters": [ { "$ref": "#/components/parameters/TenantIdHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "q" ], "properties": { "q": { "type": "string" }, "collection": { "type": "string" }, "limit": { "type": "integer" }, "from": { "type": "string", "format": "date-time" }, "to": { "type": "string", "format": "date-time" } } } } } }, "responses": { "200": { "description": "Temporally filtered results", "content": { "application/json": { "schema": { "type": "object", "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/SearchResult" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/search/hierarchical": { "post": { "operationId": "hierarchicalSearch", "summary": "Hierarchical search across memory layers", "tags": [ "Search" ], "parameters": [ { "$ref": "#/components/parameters/TenantIdHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "q" ], "properties": { "q": { "type": "string" }, "limit": { "type": "integer" } } } } } }, "responses": { "200": { "description": "Hierarchical results", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/retrieve": { "post": { "operationId": "retrieve", "summary": "Unified retrieval with auto-routing", "description": "Auto-classifies query intent and routes to optimal search backend.", "tags": [ "Search" ], "parameters": [ { "$ref": "#/components/parameters/TenantIdHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "q" ], "properties": { "q": { "type": "string" }, "mode": { "type": "string", "enum": [ "auto", "keyword", "semantic", "causal", "timeline", "discovery", "complex", "hybrid" ] }, "limit": { "type": "integer" }, "collection": { "type": "string" } } } } } }, "responses": { "200": { "description": "Retrieved results", "content": { "application/json": { "schema": { "type": "object", "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/SearchResult" } }, "mode": { "type": "string" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/ask": { "post": { "operationId": "ask", "summary": "RAG chat with LLM answer and source citations", "description": "Retrieve relevant context, run through LLM reasoning, and return a grounded answer with source citations. Supports streaming (SSE).\n", "tags": [ "Ask" ], "parameters": [ { "$ref": "#/components/parameters/TenantIdHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "q" ], "properties": { "q": { "type": "string", "description": "User question" }, "collection": { "type": "string" }, "stream": { "type": "boolean", "default": false, "description": "Enable SSE streaming" }, "language": { "type": "string", "enum": [ "pt-BR", "en" ], "default": "pt-BR" }, "limit": { "type": "integer", "default": 5, "description": "Max source documents to retrieve" } } } } } }, "responses": { "200": { "description": "RAG answer. When stream=false, returns JSON with answer and sources. When stream=true, returns text/event-stream.\n", "content": { "application/json": { "schema": { "type": "object", "properties": { "answer": { "type": "string" }, "sources": { "type": "array", "items": { "$ref": "#/components/schemas/SearchResult" } }, "trace_id": { "type": "string" } } } }, "text/event-stream": { "schema": { "type": "string", "description": "SSE stream of answer chunks" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/api/v1/traces": { "get": { "operationId": "listTraces", "summary": "List recent ask traces", "tags": [ "Ask" ], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "default": 0 } } ], "responses": { "200": { "description": "Trace log entries", "content": { "application/json": { "schema": { "type": "object", "properties": { "traces": { "type": "array", "items": { "type": "object" } }, "count": { "type": "integer" } } } } } } } } }, "/timeline/{id}": { "get": { "operationId": "timeline", "summary": "Temporal neighborhood around a document", "tags": [ "Documents" ], "parameters": [ { "$ref": "#/components/parameters/TenantIdHeader" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "before", "in": "query", "schema": { "type": "integer", "default": 5 } }, { "name": "after", "in": "query", "schema": { "type": "integer", "default": 5 } } ], "responses": { "200": { "description": "Timeline context", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/sessions": { "get": { "operationId": "listSessions", "summary": "List recent sessions", "tags": [ "Documents" ], "parameters": [ { "$ref": "#/components/parameters/TenantIdHeader" } ], "responses": { "200": { "description": "Session list", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/collections": { "get": { "operationId": "listCollections", "summary": "List all collections", "tags": [ "Documents" ], "parameters": [ { "$ref": "#/components/parameters/TenantIdHeader" } ], "responses": { "200": { "description": "Collection list", "content": { "application/json": { "schema": { "type": "object", "properties": { "collections": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "count": { "type": "integer" } } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/profile": { "get": { "operationId": "getProfile", "summary": "Get current tenant/user profile", "tags": [ "Documents" ], "parameters": [ { "$ref": "#/components/parameters/TenantIdHeader" } ], "responses": { "200": { "description": "Profile data", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/graph/causal/{id}": { "get": { "operationId": "getCausalLinks", "summary": "Get causal links for a document", "tags": [ "Graph" ], "parameters": [ { "$ref": "#/components/parameters/TenantIdHeader" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "direction", "in": "query", "schema": { "type": "string", "enum": [ "causes", "caused_by", "both" ], "default": "both" } }, { "name": "depth", "in": "query", "schema": { "type": "integer", "default": 5, "minimum": 1, "maximum": 10 } } ], "responses": { "200": { "description": "Causal link graph", "content": { "application/json": { "schema": { "type": "object", "properties": { "links": { "type": "array", "items": { "type": "object", "properties": { "docid": { "type": "string" }, "direction": { "type": "string" }, "depth": { "type": "integer" }, "reasoning": { "type": "string" } } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/graph/similar/{id}": { "get": { "operationId": "getSimilar", "summary": "Find semantically similar documents", "tags": [ "Graph" ], "parameters": [ { "$ref": "#/components/parameters/TenantIdHeader" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 5 } } ], "responses": { "200": { "description": "Similar documents", "content": { "application/json": { "schema": { "type": "object", "properties": { "similar": { "type": "array", "items": { "$ref": "#/components/schemas/SearchResult" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/graph/evolution/{id}": { "get": { "operationId": "getEvolution", "summary": "Get memory evolution timeline for a document", "tags": [ "Graph" ], "parameters": [ { "$ref": "#/components/parameters/TenantIdHeader" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 10 } } ], "responses": { "200": { "description": "Evolution timeline", "content": { "application/json": { "schema": { "type": "object", "properties": { "evolution": { "type": "array", "items": { "type": "object" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/api/v1/entities/{name}/card": { "get": { "operationId": "getEntityCard", "summary": "Get entity card by name", "tags": [ "Entity" ], "parameters": [ { "$ref": "#/components/parameters/TenantIdHeader" }, { "name": "name", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Entity name" } ], "responses": { "200": { "description": "Entity card", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "post": { "operationId": "upsertEntityCard", "summary": "Create or update an entity card", "tags": [ "Entity" ], "parameters": [ { "$ref": "#/components/parameters/TenantIdHeader" }, { "name": "name", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "summary": { "type": "string" }, "aliases": { "type": "array", "items": { "type": "string" } }, "metadata": { "type": "object", "additionalProperties": true } } } } } }, "responses": { "200": { "description": "Entity card upserted", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } }, "patch": { "tags": [ "Runtime" ], "summary": "Registered on this process; not yet in docs/reference/openapi.yaml", "operationId": "live_PATCH__api_v1_entities_name_card", "x-valorbrain-live": true, "responses": { "200": { "description": "See the running handler" } } }, "delete": { "tags": [ "Runtime" ], "summary": "Registered on this process; not yet in docs/reference/openapi.yaml", "operationId": "live_DELETE__api_v1_entities_name_card", "x-valorbrain-live": true, "responses": { "200": { "description": "See the running handler" } } } }, "/api/v1/triples": { "post": { "operationId": "createTriple", "summary": "Create an SPO triple", "description": "Create a subject-predicate-object triple. Resolves entity names to IDs.", "tags": [ "Entity" ], "parameters": [ { "$ref": "#/components/parameters/TenantIdHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "subject", "predicate", "object" ], "properties": { "subject": { "type": "string" }, "predicate": { "type": "string" }, "object": { "type": "string" }, "confidence": { "type": "number", "default": 0.8 } } } } } }, "responses": { "200": { "description": "Triple created", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "triple": { "type": "object" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/foundations": { "get": { "operationId": "getFoundations", "summary": "Get Tier-0 foundation context", "tags": [ "Foundations" ], "parameters": [ { "$ref": "#/components/parameters/TenantIdHeader" } ], "responses": { "200": { "description": "Foundation documents", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/api/v1/state": { "get": { "operationId": "getState", "summary": "Get structured engine state", "tags": [ "Foundations" ], "parameters": [ { "$ref": "#/components/parameters/TenantIdHeader" } ], "responses": { "200": { "description": "Structured state", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/api/v1/foundations": { "post": { "operationId": "createFoundation", "summary": "Create a foundation document", "tags": [ "Foundations" ], "parameters": [ { "$ref": "#/components/parameters/TenantIdHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "path", "content" ], "properties": { "path": { "type": "string" }, "content": { "type": "string" }, "title": { "type": "string" }, "layer": { "type": "string" } } } } } }, "responses": { "200": { "description": "Foundation created", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/api/v1/foundations/{id}": { "put": { "operationId": "updateFoundation", "summary": "Update a foundation document", "tags": [ "Foundations" ], "parameters": [ { "$ref": "#/components/parameters/TenantIdHeader" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "content": { "type": "string" }, "title": { "type": "string" } } } } } }, "responses": { "200": { "description": "Foundation updated", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "delete": { "operationId": "deleteFoundation", "summary": "Delete a foundation document", "tags": [ "Foundations" ], "parameters": [ { "$ref": "#/components/parameters/TenantIdHeader" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Foundation deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/v1/foundations/{id}/promote": { "post": { "operationId": "promoteFoundation", "summary": "Promote a foundation to a higher layer", "tags": [ "Foundations" ], "parameters": [ { "$ref": "#/components/parameters/TenantIdHeader" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Foundation promoted", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/api/v1/agents/signup": { "post": { "operationId": "agentSignup", "summary": "Register a new agent (public)", "description": "Public endpoint — no auth required. Creates a shadow tenant and returns an API key.\n", "tags": [ "Agents" ], "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "agent_name" ], "properties": { "agent_name": { "type": "string" }, "capabilities": { "type": "array", "items": { "type": "string" } }, "metadata": { "type": "object", "additionalProperties": true } } } } } }, "responses": { "200": { "description": "Agent registered with API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "tenant_id": { "type": "string" }, "api_key": { "type": "string" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" } } } }, "/api/v1/agents/identify": { "post": { "operationId": "agentIdentify", "summary": "Identify an agent by API key", "tags": [ "Agents" ], "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "key" ], "properties": { "key": { "type": "string" } } } } } }, "responses": { "200": { "description": "Agent identity", "content": { "application/json": { "schema": { "type": "object", "properties": { "agent_name": { "type": "string" }, "tenant_id": { "type": "string" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/api/v1/agents/claim": { "post": { "operationId": "agentClaim", "summary": "Request ownership claim for an agent", "tags": [ "Agents" ], "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "agent_name", "email" ], "properties": { "agent_name": { "type": "string" }, "email": { "type": "string", "format": "email" } } } } } }, "responses": { "200": { "description": "Claim request initiated", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/BadRequest" } } } }, "/api/v1/agents/claim/verify": { "post": { "operationId": "agentClaimVerify", "summary": "Verify an agent ownership claim", "tags": [ "Agents" ], "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "token" ], "properties": { "token": { "type": "string" } } } } } }, "responses": { "200": { "description": "Claim verified", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "api_key": { "type": "string" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" } } } }, "/api/v1/workspace/focus": { "get": { "operationId": "listFocus", "summary": "List current workspace focus items", "tags": [ "Workspace" ], "parameters": [ { "$ref": "#/components/parameters/TenantIdHeader" } ], "responses": { "200": { "description": "Focus items", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } }, "post": { "operationId": "setFocus", "summary": "Set workspace focus", "tags": [ "Workspace" ], "parameters": [ { "$ref": "#/components/parameters/TenantIdHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object" } } } } } } }, "responses": { "200": { "description": "Focus updated", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/api/v1/workspace/sessions": { "get": { "operationId": "listWorkspaceSessions", "summary": "List workspace sessions", "tags": [ "Workspace" ], "parameters": [ { "$ref": "#/components/parameters/TenantIdHeader" } ], "responses": { "200": { "description": "Session list", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/api/v1/workspace/handoffs": { "get": { "operationId": "listHandoffs", "summary": "List workspace handoffs", "tags": [ "Workspace" ], "parameters": [ { "$ref": "#/components/parameters/TenantIdHeader" } ], "responses": { "200": { "description": "Handoff list", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/api/v1/workspace/state": { "get": { "operationId": "getWorkspaceState", "summary": "Get workspace state document", "tags": [ "Workspace" ], "parameters": [ { "$ref": "#/components/parameters/TenantIdHeader" } ], "responses": { "200": { "description": "Workspace state", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/api/v1/users": { "get": { "operationId": "listUsers", "summary": "List users in tenant", "tags": [ "Users" ], "parameters": [ { "$ref": "#/components/parameters/TenantIdHeader" } ], "responses": { "200": { "description": "User list", "content": { "application/json": { "schema": { "type": "object", "properties": { "users": { "type": "array", "items": { "type": "object" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } }, "post": { "operationId": "createUser", "summary": "Create a user", "tags": [ "Users" ], "parameters": [ { "$ref": "#/components/parameters/TenantIdHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "email" ], "properties": { "email": { "type": "string", "format": "email" }, "name": { "type": "string" }, "role": { "type": "string" } } } } } }, "responses": { "200": { "description": "User created", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/api/v1/users/{userId}": { "put": { "operationId": "updateUser", "summary": "Update a user", "tags": [ "Users" ], "parameters": [ { "$ref": "#/components/parameters/TenantIdHeader" }, { "name": "userId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "role": { "type": "string" }, "metadata": { "type": "object" } } } } } }, "responses": { "200": { "description": "User updated", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/v1/identity": { "get": { "operationId": "getIdentity", "summary": "Get current identity", "tags": [ "Identity" ], "parameters": [ { "$ref": "#/components/parameters/TenantIdHeader" } ], "responses": { "200": { "description": "Identity profile", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "email": { "type": "string" }, "tenant_id": { "type": "string" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } }, "put": { "operationId": "updateIdentity", "summary": "Update current identity", "tags": [ "Identity" ], "parameters": [ { "$ref": "#/components/parameters/TenantIdHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "email": { "type": "string" }, "preferences": { "type": "object" } } } } } }, "responses": { "200": { "description": "Identity updated", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/api/v1/credits/balance": { "get": { "operationId": "getCreditsBalance", "summary": "Get credit balance", "tags": [ "Billing" ], "parameters": [ { "$ref": "#/components/parameters/TenantIdHeader" } ], "responses": { "200": { "description": "Credit balance", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreditBalance" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/api/v1/credits/transactions": { "get": { "operationId": "getCreditsTransactions", "summary": "Get credit transaction history", "tags": [ "Billing" ], "parameters": [ { "$ref": "#/components/parameters/TenantIdHeader" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50 } } ], "responses": { "200": { "description": "Transaction list", "content": { "application/json": { "schema": { "type": "object", "properties": { "transactions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "amount": { "type": "number" }, "action": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" } } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/api/v1/credits/grant": { "post": { "operationId": "grantCredits", "summary": "Grant credits to tenant", "description": "Repeatable manual operator adjustment; the required reason is recorded in the credit ledger.", "tags": [ "Billing" ], "security": [ { "moneyAdminAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/MoneyTenantIdHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "amount", "reason" ], "properties": { "amount": { "type": "number", "exclusiveMinimum": 0 }, "reason": { "type": "string", "minLength": 1 }, "metadata": { "type": "object", "additionalProperties": true } } } } } }, "responses": { "200": { "description": "Credits granted", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "balance_after" ], "properties": { "ok": { "type": "boolean" }, "balance_after": { "type": "number" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/api/v1/pricing/actions": { "get": { "operationId": "listPricingActions", "summary": "List pricing actions", "tags": [ "Billing" ], "parameters": [ { "$ref": "#/components/parameters/TenantIdHeader" } ], "responses": { "200": { "description": "Pricing action list", "content": { "application/json": { "schema": { "type": "object", "properties": { "actions": { "type": "array", "items": { "type": "object", "properties": { "action": { "type": "string" }, "cost": { "type": "number" }, "currency": { "type": "string" } } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/api/v1/pricing/actions/{action}": { "put": { "operationId": "setPricingAction", "summary": "Set pricing for an action", "tags": [ "Billing" ], "security": [ { "moneyAdminAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/MoneyTenantIdHeader" }, { "name": "action", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "cost" ], "properties": { "cost": { "type": "number" } } } } } }, "responses": { "200": { "description": "Pricing updated", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/api/v1/plans": { "get": { "operationId": "listPlans", "summary": "List available subscription plans", "tags": [ "Billing" ], "responses": { "200": { "description": "Plan list", "content": { "application/json": { "schema": { "type": "object", "properties": { "plans": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "credits": { "type": "number" }, "price": { "type": "number" } } } } } } } } } } } }, "/api/v1/subscription": { "get": { "operationId": "getSubscription", "summary": "Get current subscription", "tags": [ "Billing" ], "parameters": [ { "$ref": "#/components/parameters/TenantIdHeader" } ], "responses": { "200": { "description": "Subscription details", "content": { "application/json": { "schema": { "type": "object", "properties": { "plan_id": { "type": "string" }, "status": { "type": "string" }, "current_period_end": { "type": "string", "format": "date-time" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } }, "put": { "operationId": "updateSubscription", "summary": "Update subscription plan", "tags": [ "Billing" ], "security": [ { "moneyAdminAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/MoneyTenantIdHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "plan_id": { "type": "string" } } } } } }, "responses": { "200": { "description": "Subscription updated", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/api/v1/subscription/grant": { "post": { "operationId": "grantSubscriptionCredits", "summary": "Grant legacy Stripe invoice credits idempotently", "description": "Compatibility endpoint for older Stripe contracts with monthly credits. Writes a credit_grant event with source stripe:invoice and source_id equal to invoice_id. It does not activate or change the subscription itself.\n", "tags": [ "Billing" ], "security": [ { "moneyAdminAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/MoneyTenantIdHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionCreditGrantRequest" } } } }, "responses": { "200": { "description": "Credits granted once, or an identical invoice replay skipped", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionCreditGrantResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/BillingConflict" }, "422": { "$ref": "#/components/responses/BillingUnprocessable" } } } }, "/api/v1/billing/events/apply": { "post": { "operationId": "applyBillingEvent", "summary": "Apply a verified billing event idempotently", "description": "Applies an externally verified billing effect in one tenant-scoped transaction. The tenant row is locked before replay lookup and before any subscription lock. Subscription events update entitlement/quota; credit_grant updates only balance and ledger and returns subscription null. Older periods are journaled as immutable stale no-ops. The final non-null result is inserted once with the event after all effects are built; a global source-key or settlement-proof conflict rolls back every effect. Payment verification and private signing material stay outside this API.\n", "tags": [ "Billing" ], "security": [ { "moneyAdminAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/MoneyTenantIdHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BillingEventApplyRequest" } } } }, "responses": { "200": { "description": "Event applied once or returned as an identical replay", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BillingEventApplyResult" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/BillingConflict" }, "422": { "$ref": "#/components/responses/BillingUnprocessable" } } } }, "/api/v1/billing/events": { "get": { "operationId": "findBillingEvents", "summary": "Find tenant billing events for reconciliation", "description": "Admin-only, tenant-scoped journal lookup. Supply event_id, the complete source/source_id pair, or provider_subscription_id. Combined selectors use AND. Results are ordered by created_at descending and never expose another tenant's event.\n", "tags": [ "Billing" ], "security": [ { "moneyAdminAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/MoneyTenantIdHeader" }, { "name": "event_id", "in": "query", "schema": { "type": "string", "format": "uuid" } }, { "name": "source", "in": "query", "description": "Must be supplied together with source_id.", "schema": { "type": "string", "maxLength": 128 } }, { "name": "source_id", "in": "query", "description": "Must be supplied together with source.", "schema": { "type": "string", "maxLength": 512 } }, { "name": "provider_subscription_id", "in": "query", "schema": { "type": "string", "maxLength": 512 } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 20 } } ], "responses": { "200": { "description": "Matching tenant billing events", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BillingEventsResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/api/v1/admin/tenants": { "post": { "operationId": "adminCreateTenant", "summary": "Create a tenant (admin only)", "tags": [ "Admin" ], "security": [ { "adminSecret": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": true } } } } } }, "responses": { "200": { "description": "Tenant created", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "tenant_id": { "type": "string" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/api/v1/admin/tenants/{tenantId}/users": { "post": { "operationId": "adminCreateUser", "summary": "Create a user in a tenant (admin only)", "tags": [ "Admin" ], "security": [ { "adminSecret": [] } ], "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "email" ], "properties": { "email": { "type": "string", "format": "email" }, "name": { "type": "string" }, "role": { "type": "string" } } } } } }, "responses": { "200": { "description": "User created", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/api/v1/admin/tenants/{tenantId}": { "delete": { "operationId": "adminDeleteTenant", "summary": "Delete a tenant (admin only)", "tags": [ "Admin" ], "security": [ { "adminSecret": [] } ], "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Tenant deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/api/v1/admin/errors": { "get": { "operationId": "adminListErrors", "summary": "List error log (admin only)", "tags": [ "Admin" ], "security": [ { "adminSecret": [] } ], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50 } }, { "name": "unresolved_only", "in": "query", "schema": { "type": "boolean", "default": true } } ], "responses": { "200": { "description": "Error list", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/api/v1/admin/errors/{errorId}/resolve": { "post": { "operationId": "adminResolveError", "summary": "Resolve an error (admin only)", "tags": [ "Admin" ], "security": [ { "adminSecret": [] } ], "parameters": [ { "name": "errorId", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Error resolved", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/api/v1/admin/test-error": { "get": { "operationId": "adminTestError", "summary": "Trigger a test error (admin only)", "tags": [ "Admin" ], "security": [ { "adminSecret": [] } ], "responses": { "200": { "description": "Test error triggered", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/.well-known/oauth-authorization-server": { "get": { "operationId": "oauthAsMetadata", "summary": "OAuth authorization server metadata", "description": "Public discovery endpoint per RFC 9414.", "tags": [ "OAuth" ], "security": [], "responses": { "200": { "description": "Authorization server metadata", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/.well-known/oauth-protected-resource": { "get": { "operationId": "oauthRsMetadata", "summary": "OAuth protected resource metadata", "description": "Public discovery endpoint per RFC 9728.", "tags": [ "OAuth" ], "security": [], "responses": { "200": { "description": "Protected resource metadata", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/oauth/register": { "post": { "operationId": "oauthRegister", "summary": "Dynamic client registration", "tags": [ "OAuth" ], "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "client_name": { "type": "string" }, "redirect_uris": { "type": "array", "items": { "type": "string" } }, "grant_types": { "type": "array", "items": { "type": "string" } } } } } } }, "responses": { "201": { "description": "Client registered", "content": { "application/json": { "schema": { "type": "object", "properties": { "client_id": { "type": "string" }, "client_secret": { "type": "string" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" } } } }, "/oauth/authorize": { "get": { "operationId": "oauthAuthorize", "summary": "OAuth authorization endpoint", "description": "Redirects to consent page.", "tags": [ "OAuth" ], "security": [], "parameters": [ { "name": "response_type", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "client_id", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "redirect_uri", "in": "query", "schema": { "type": "string" } }, { "name": "scope", "in": "query", "schema": { "type": "string" } }, { "name": "state", "in": "query", "schema": { "type": "string" } } ], "responses": { "302": { "description": "Redirect to consent page" }, "400": { "$ref": "#/components/responses/BadRequest" } } } }, "/oauth/consent": { "get": { "operationId": "oauthConsentPage", "summary": "OAuth consent page", "tags": [ "OAuth" ], "security": [], "responses": { "200": { "description": "HTML consent form" } } }, "post": { "operationId": "oauthConsentSubmit", "summary": "Submit OAuth consent", "tags": [ "OAuth" ], "security": [], "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object" } } } }, "responses": { "302": { "description": "Redirect back to client" } } } }, "/oauth/token": { "post": { "operationId": "oauthToken", "summary": "OAuth token exchange", "tags": [ "OAuth" ], "security": [], "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "required": [ "grant_type" ], "properties": { "grant_type": { "type": "string" }, "code": { "type": "string" }, "client_id": { "type": "string" }, "client_secret": { "type": "string" }, "redirect_uri": { "type": "string" } } } } } }, "responses": { "200": { "description": "Token response", "content": { "application/json": { "schema": { "type": "object", "properties": { "access_token": { "type": "string" }, "token_type": { "type": "string" }, "expires_in": { "type": "integer" }, "refresh_token": { "type": "string" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" } } } }, "/oauth/revoke": { "post": { "operationId": "oauthRevoke", "summary": "Revoke an OAuth token", "tags": [ "OAuth" ], "security": [], "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "required": [ "token" ], "properties": { "token": { "type": "string" } } } } } }, "responses": { "200": { "description": "Token revoked" } } } }, "/api/v1/mcp/tokens": { "get": { "operationId": "listMcpTokens", "summary": "List MCP API tokens", "tags": [ "MCP Tokens" ], "parameters": [ { "$ref": "#/components/parameters/TenantIdHeader" } ], "responses": { "200": { "description": "Token list", "content": { "application/json": { "schema": { "type": "object", "properties": { "tokens": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "prefix": { "type": "string" }, "is_active": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" } } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } }, "post": { "operationId": "createMcpToken", "summary": "Create an MCP API token", "tags": [ "MCP Tokens" ], "parameters": [ { "$ref": "#/components/parameters/TenantIdHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string" }, "expires_at": { "type": "string", "format": "date-time" } } } } } }, "responses": { "200": { "description": "Token created (full key returned only once)", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "id": { "type": "string" }, "key": { "type": "string", "description": "Full API key (shown only at creation)" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/api/v1/mcp/tokens/{tokenId}": { "get": { "operationId": "getMcpToken", "summary": "Get MCP token details", "tags": [ "MCP Tokens" ], "parameters": [ { "$ref": "#/components/parameters/TenantIdHeader" }, { "name": "tokenId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Token details", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "put": { "operationId": "updateMcpToken", "summary": "Update MCP token", "tags": [ "MCP Tokens" ], "parameters": [ { "$ref": "#/components/parameters/TenantIdHeader" }, { "name": "tokenId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "is_active": { "type": "boolean" } } } } } }, "responses": { "200": { "description": "Token updated", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "delete": { "operationId": "deleteMcpToken", "summary": "Delete MCP token", "tags": [ "MCP Tokens" ], "parameters": [ { "$ref": "#/components/parameters/TenantIdHeader" }, { "name": "tokenId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Token deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/v1/acl/me": { "get": { "operationId": "aclMe", "summary": "Effective source-ACL domains of the caller (the \"why\" trace)", "description": "Union of user + role + agent grants with the provenance of each grant (who granted, reason, temporal validity). Feeds the permission trace of the governance simulator. Requires a caller identity (bound user or agent persona); 401 otherwise, with no regime structure leaked.\n", "tags": [ "Governance" ], "parameters": [ { "$ref": "#/components/parameters/TenantIdHeader" } ], "responses": { "200": { "description": "ACL trace for the caller", "content": { "application/json": { "schema": { "type": "object", "properties": { "tenant_id": { "type": "string" }, "identity": { "type": "object", "properties": { "user_id": { "type": [ "string", "null" ] }, "role": { "type": [ "string", "null" ] }, "agent": { "type": [ "string", "null" ] } } }, "acl": { "type": "object", "properties": { "active": { "type": "boolean" }, "state": { "type": "string" }, "allowed_domains": { "type": "array", "items": { "type": "string" } }, "denied_domains": { "type": "array", "items": { "type": "string" } }, "known_domains": { "type": "array", "items": { "type": "string" } }, "hidden_documents": { "type": "integer" }, "grants": { "type": "array", "items": { "type": "object" } } } }, "trace": { "type": "object" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/api/v1/acl/grants": { "get": { "operationId": "listAclGrants", "summary": "List source-ACL grants (ADMIN)", "tags": [ "Governance" ], "parameters": [ { "$ref": "#/components/parameters/TenantIdHeader" }, { "name": "subject_kind", "in": "query", "schema": { "type": "string", "enum": [ "user", "role", "agent" ] } }, { "name": "subject_id", "in": "query", "schema": { "type": "string" } }, { "name": "domain", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Grant list + domain mappings", "content": { "application/json": { "schema": { "type": "object", "properties": { "grants": { "type": "array", "items": { "type": "object" } }, "domains": { "type": "array", "items": { "type": "object" } } } } } } }, "403": { "$ref": "#/components/responses/Unauthorized" } } }, "post": { "operationId": "createAclGrant", "summary": "Create a source-ACL grant (ADMIN; reason required)", "tags": [ "Governance" ], "parameters": [ { "$ref": "#/components/parameters/TenantIdHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "subject_kind", "subject_id", "domain", "reason" ], "properties": { "subject_kind": { "type": "string", "enum": [ "user", "role", "agent" ] }, "subject_id": { "type": "string" }, "domain": { "type": "string" }, "reason": { "type": "string" }, "valid_from": { "type": "string", "format": "date-time", "nullable": true }, "valid_to": { "type": "string", "format": "date-time", "nullable": true } } } } } }, "responses": { "201": { "description": "Grant created" }, "409": { "description": "Grant already exists" } } } }, "/api/v1/acl/grants/{grantId}": { "delete": { "operationId": "revokeAclGrant", "summary": "Revoke a source-ACL grant (ADMIN)", "tags": [ "Governance" ], "parameters": [ { "$ref": "#/components/parameters/TenantIdHeader" }, { "name": "grantId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Grant revoked" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/v1/acl/domains": { "get": { "operationId": "listAclDomains", "summary": "The collection→domain regime (ADMIN)", "description": "Collections without a mapping sit outside the ACL regime — readable by everyone, even with the flag on.", "tags": [ "Governance" ], "parameters": [ { "$ref": "#/components/parameters/TenantIdHeader" } ], "responses": { "200": { "description": "Domain mappings" }, "403": { "$ref": "#/components/responses/Forbidden" } } }, "post": { "operationId": "upsertAclDomain", "summary": "Upsert one collection→domain mapping (ADMIN)", "tags": [ "Governance" ], "parameters": [ { "$ref": "#/components/parameters/TenantIdHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "collection", "domain" ], "properties": { "collection": { "type": "string" }, "domain": { "type": "string", "description": "lowercase business-domain slug (gtm", "finance": null, "…)": null } } } } } }, "responses": { "201": { "description": "Mapping upserted (applies on the next request)" }, "400": { "$ref": "#/components/responses/BadRequest" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/api/v1/acl/domains/{collection}": { "delete": { "operationId": "removeAclDomain", "summary": "Remove a mapping — the collection leaves the ACL regime (ADMIN)", "tags": [ "Governance" ], "parameters": [ { "$ref": "#/components/parameters/TenantIdHeader" }, { "name": "collection", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Mapping removed" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/v1/read-log": { "get": { "operationId": "queryReadLog", "summary": "The query read-log — \"who read which version\" (LGPD tier)", "description": "One row per retrieval query (governance spec 2026-09-24 §2.2): identity in the secret_access_log pattern (actor user/agent/harness, token prefix, session), channel/operation, the query as a HASH (the text is never stored — LGPD) and docs_touched, the (doc_hash, revision_count) pairs frozen at read time (cap 20). Retention: 90 hot days plus the read_log_monthly anonymous rollup. Access is privileged: persona (vbm_) tokens need the handler-scoped `read_log:read` scope (legacy `read` and scopeless tokens do NOT cover it); workspace credentials need the SaaS-resolved ADMIN role. Every query of this log is itself audited in mutation_audit as `read_log.query`.\n", "tags": [ "Governance" ], "parameters": [ { "$ref": "#/components/parameters/TenantIdHeader" }, { "name": "doc", "in": "query", "schema": { "type": "string" }, "description": "Doc hash (full or prefix) — who read THIS document" }, { "name": "actor", "in": "query", "schema": { "type": "string" }, "description": "Actor user id — what THIS person read" }, { "name": "channel", "in": "query", "schema": { "type": "string", "enum": [ "mcp", "rest", "hook", "cli" ] } }, { "name": "operation", "in": "query", "schema": { "type": "string" } }, { "name": "from", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "to", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } } ], "responses": { "200": { "description": "Read-log entries (hashes only — no query text, no document content)", "content": { "application/json": { "schema": { "type": "object", "properties": { "tenant_id": { "type": "string" }, "total": { "type": "integer" }, "entries": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "created_at": { "type": "string" }, "actor_user_id": { "type": [ "string", "null" ] }, "actor_agent": { "type": [ "string", "null" ] }, "actor_harness": { "type": [ "string", "null" ] }, "token_prefix": { "type": [ "string", "null" ] }, "session_id": { "type": [ "string", "null" ] }, "channel": { "type": "string" }, "operation": { "type": "string" }, "query_hash": { "type": [ "string", "null" ] }, "result_count": { "type": "integer" }, "docs_touched": { "type": [ "array", "null" ], "description": "Up to 20 {h, v} (doc hash, revision) pairs frozen at read time", "items": { "type": "object", "properties": { "h": { "type": "string" }, "v": { "type": [ "number", "null" ] } } } } } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/api/v1/read-log/erase": { "post": { "operationId": "eraseReadLogActor", "summary": "LGPD erasure of a data subject's identity in the read-log", "description": "Rights of the holder (governance spec 2026-09-24 §2.7): anonymizes the actor (actor_user_id → 'erased') on every read-log row of the tenant via the SECURITY DEFINER function from migration 0223 — the only mutation the append-only table admits. The access facts (which documents, which versions, when) stay; the identity is gone, so the remaining rows no longer identify the person; the anonymous read_log_monthly rollup is preserved. Tier: persona tokens need explicit `read_log:write`; workspace credentials need the SaaS-resolved ADMIN role. Audited in mutation_audit as `read_log.erase`.\n", "tags": [ "Governance" ], "parameters": [ { "$ref": "#/components/parameters/TenantIdHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "actor_user_id" ], "properties": { "actor_user_id": { "type": "string", "format": "uuid" } } } } } }, "responses": { "200": { "description": "Actor anonymized (anonymized = rows affected)" }, "400": { "$ref": "#/components/responses/BadRequest" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/metrics": { "get": { "operationId": "metrics", "summary": "Prometheus metrics", "description": "Public endpoint for Prometheus scraping. Low cardinality.", "tags": [ "Observability" ], "security": [], "responses": { "200": { "description": "Prometheus text format metrics", "content": { "text/plain": { "schema": { "type": "string" } } } } } } }, "/api/v1/trajectories": { "get": { "operationId": "listTrajectories", "summary": "List retrieval trajectories", "tags": [ "Observability" ], "parameters": [ { "$ref": "#/components/parameters/TenantIdHeader" } ], "responses": { "200": { "description": "Trajectory list", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/api/v1/roi": { "get": { "operationId": "getROI", "summary": "Get ROI metrics", "tags": [ "Observability" ], "parameters": [ { "$ref": "#/components/parameters/TenantIdHeader" } ], "responses": { "200": { "description": "ROI data", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/api/v1/digest/send": { "post": { "operationId": "sendDigest", "summary": "Send email digest", "tags": [ "Observability" ], "parameters": [ { "$ref": "#/components/parameters/TenantIdHeader" } ], "responses": { "200": { "description": "Digest sent", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/api/v1/features": { "get": { "operationId": "listFeatures", "summary": "List feature flags", "tags": [ "Observability" ], "parameters": [ { "$ref": "#/components/parameters/TenantIdHeader" } ], "responses": { "200": { "description": "Feature flags", "content": { "application/json": { "schema": { "type": "object", "properties": { "features": { "type": "object", "additionalProperties": { "type": "boolean" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } }, "post": { "operationId": "setFeature", "summary": "Set a feature flag", "tags": [ "Observability" ], "parameters": [ { "$ref": "#/components/parameters/TenantIdHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name", "enabled" ], "properties": { "name": { "type": "string" }, "enabled": { "type": "boolean" } } } } } }, "responses": { "200": { "description": "Feature flag updated", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/api/v1/config": { "get": { "operationId": "getTenantConfig", "summary": "Get tenant configuration", "tags": [ "Observability" ], "parameters": [ { "$ref": "#/components/parameters/TenantIdHeader" } ], "responses": { "200": { "description": "Tenant config", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/api/v1/config/{key}": { "put": { "operationId": "setTenantConfigKey", "summary": "Set a tenant configuration key", "tags": [ "Observability" ], "parameters": [ { "$ref": "#/components/parameters/TenantIdHeader" }, { "name": "key", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[a-zA-Z][a-zA-Z0-9_]*$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "Config key updated", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/api/v1/criteria": { "get": { "operationId": "getCriteria", "summary": "Get retrieval criteria", "tags": [ "Observability" ], "parameters": [ { "$ref": "#/components/parameters/TenantIdHeader" } ], "responses": { "200": { "description": "Criteria list", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } }, "put": { "operationId": "setCriteria", "summary": "Set retrieval criteria", "tags": [ "Observability" ], "parameters": [ { "$ref": "#/components/parameters/TenantIdHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "Criteria updated", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/api/v1/benchmark/run": { "post": { "operationId": "benchmarkRun", "summary": "Run a benchmark", "tags": [ "Observability" ], "parameters": [ { "$ref": "#/components/parameters/TenantIdHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "queries": { "type": "array", "items": { "type": "string" } }, "expected": { "type": "array", "items": { "type": "object" } } } } } } }, "responses": { "200": { "description": "Benchmark results", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/api/v1/benchmark/runs": { "get": { "operationId": "benchmarkListRuns", "summary": "List benchmark runs", "tags": [ "Observability" ], "parameters": [ { "$ref": "#/components/parameters/TenantIdHeader" } ], "responses": { "200": { "description": "Benchmark run list", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/api/v1/benchmark/compare": { "get": { "operationId": "benchmarkCompare", "summary": "Compare benchmark runs", "tags": [ "Observability" ], "parameters": [ { "$ref": "#/components/parameters/TenantIdHeader" }, { "name": "run_a", "in": "query", "schema": { "type": "string" } }, { "name": "run_b", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Comparison results", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/api/v1/memory/recall": { "post": { "operationId": "memoryRecall", "summary": "Token-budgeted memory recall", "description": "Pull category-ranked memory in a fixed token budget (mem0-style).", "tags": [ "Observability" ], "parameters": [ { "$ref": "#/components/parameters/TenantIdHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "query": { "type": "string" }, "budget": { "type": "integer", "default": 1500 }, "format": { "type": "string", "enum": [ "json", "markdown" ], "default": "markdown" } } } } } }, "responses": { "200": { "description": "Budgeted memory recall", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/api/v1/memory/used": { "post": { "operationId": "memoryUsed", "summary": "Declare which memories an answer actually used (quality loop)", "description": "REST mirror of the MCP `memory_used` tool. The agent declares the docids ('#ab12cd' hex prefixes) or paths of the memories it relied on; optionally a verdict (\"confirmed\"/\"corrected\") when the user reacted to what the memory said. Feeds usage coverage, ranking signals and the trust loop. Infra agents excluded downstream.\n", "tags": [ "Observability" ], "parameters": [ { "$ref": "#/components/parameters/TenantIdHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "docids" ], "properties": { "docids": { "type": "array", "items": { "type": "string" }, "minItems": 1, "description": "Docids ('#ab12cd') or document paths" }, "verdict": { "type": "string", "enum": [ "confirmed", "corrected" ], "description": "User confirmed or corrected what the memory said (V5)" }, "note": { "type": "string", "description": "Why the memories were useful" } } } } } }, "responses": { "200": { "description": "Declaration recorded", "content": { "application/json": { "schema": { "type": "object", "properties": { "declared": { "type": "integer" }, "marked": { "type": "integer" }, "unresolved": { "type": "array", "items": { "type": "string" } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/v1/tenant/value-summary": { "get": { "operationId": "tenantValueSummary", "summary": "Counted value by usage family for the Impact home and digest", "description": "Hero numbers (searches served, contexts delivered, memories recorded), usage families, quality coverage (sessions with declared memory_used over sessions with delivered context), active agents, knowledge timeline and per-operation breakdown. Completed days are served from the pre-computed value_daily table; the current day aggregates live; days the nightly job missed fall back to live aggregation and are reported in stale_days. Infra agents excluded from every family.\n", "tags": [ "Observability" ], "parameters": [ { "$ref": "#/components/parameters/TenantIdHeader" }, { "name": "period", "in": "query", "schema": { "type": "string", "enum": [ "today", "yesterday", "7d", "30d" ], "default": "7d" }, "description": "Window (UTC days); yesterday is the closed digest day" } ], "responses": { "200": { "description": "Value summary", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/api/v1/memory/health": { "get": { "operationId": "memoryHealth", "summary": "Memory health diagnostics", "tags": [ "Observability" ], "parameters": [ { "$ref": "#/components/parameters/TenantIdHeader" } ], "responses": { "200": { "description": "Health diagnostics", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/api/v1/privacy/preview": { "post": { "operationId": "privacyPreview", "summary": "Preview privacy extraction", "tags": [ "Observability" ], "parameters": [ { "$ref": "#/components/parameters/TenantIdHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "content" ], "properties": { "content": { "type": "string" } } } } } }, "responses": { "200": { "description": "Privacy preview", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/api/v1/privacy/sanitize": { "post": { "operationId": "privacySanitize", "summary": "Sanitize PII from content", "tags": [ "Observability" ], "parameters": [ { "$ref": "#/components/parameters/TenantIdHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "content" ], "properties": { "content": { "type": "string" } } } } } }, "responses": { "200": { "description": "Sanitized content", "content": { "application/json": { "schema": { "type": "object", "properties": { "sanitized": { "type": "string" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/api/v1/privacy/restore": { "post": { "operationId": "privacyRestore", "summary": "Restore sanitized content", "tags": [ "Observability" ], "parameters": [ { "$ref": "#/components/parameters/TenantIdHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "content", "tokens" ], "properties": { "content": { "type": "string" }, "tokens": { "type": "array", "items": { "type": "object" } } } } } } }, "responses": { "200": { "description": "Restored content", "content": { "application/json": { "schema": { "type": "object", "properties": { "restored": { "type": "string" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/api/v1/foresights": { "get": { "operationId": "listForesights", "summary": "List foresight predictions", "tags": [ "Observability" ], "parameters": [ { "$ref": "#/components/parameters/TenantIdHeader" } ], "responses": { "200": { "description": "Foresight list", "content": { "application/json": { "schema": { "type": "object", "properties": { "foresights": { "type": "array", "items": { "type": "object" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/api/v1/foresights/sweep": { "post": { "operationId": "sweepForesights", "summary": "Trigger foresight sweep", "tags": [ "Observability" ], "parameters": [ { "$ref": "#/components/parameters/TenantIdHeader" } ], "responses": { "200": { "description": "Sweep initiated", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/api/v1/foresights/{id}": { "get": { "operationId": "getForesight", "summary": "Get a specific foresight", "tags": [ "Observability" ], "parameters": [ { "$ref": "#/components/parameters/TenantIdHeader" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Foresight details", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "patch": { "operationId": "patchForesight", "summary": "Update a foresight", "tags": [ "Observability" ], "parameters": [ { "$ref": "#/components/parameters/TenantIdHeader" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "Foresight updated", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "delete": { "operationId": "deleteForesight", "summary": "Delete a foresight", "tags": [ "Observability" ], "parameters": [ { "$ref": "#/components/parameters/TenantIdHeader" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Foresight deleted", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/v1/conflicts": { "get": { "operationId": "listConflicts", "summary": "List canonical conflicts", "tags": [ "Canonical" ], "parameters": [ { "$ref": "#/components/parameters/TenantIdHeader" } ], "responses": { "200": { "description": "Conflict list", "content": { "application/json": { "schema": { "type": "object", "properties": { "conflicts": { "type": "array", "items": { "type": "object" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/api/v1/proposals": { "get": { "operationId": "listProposals", "summary": "List update proposals", "tags": [ "Canonical" ], "parameters": [ { "$ref": "#/components/parameters/TenantIdHeader" } ], "responses": { "200": { "description": "Proposal list", "content": { "application/json": { "schema": { "type": "object", "properties": { "proposals": { "type": "array", "items": { "type": "object" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/api/v1/proposals/{id}/pick": { "post": { "operationId": "pickProposal", "summary": "Pick a proposal variant", "tags": [ "Canonical" ], "parameters": [ { "$ref": "#/components/parameters/TenantIdHeader" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "variant": { "type": "string" } } } } } }, "responses": { "200": { "description": "Proposal picked", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/api/v1/proposals/{id}/resolve": { "post": { "operationId": "resolveProposal", "summary": "Resolve a proposal", "tags": [ "Canonical" ], "parameters": [ { "$ref": "#/components/parameters/TenantIdHeader" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" } } } } } }, "responses": { "200": { "description": "Proposal resolved", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/api/v1/probes": { "get": { "operationId": "listProbes", "summary": "List validation probes", "tags": [ "Canonical" ], "parameters": [ { "$ref": "#/components/parameters/TenantIdHeader" } ], "responses": { "200": { "description": "Probe list", "content": { "application/json": { "schema": { "type": "object", "properties": { "probes": { "type": "array", "items": { "type": "object" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/api/v1/canonical/run": { "post": { "operationId": "canonicalRun", "summary": "Trigger canonical detection run", "tags": [ "Canonical" ], "parameters": [ { "$ref": "#/components/parameters/TenantIdHeader" } ], "responses": { "200": { "description": "Canonical run initiated", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/api/v1/canonical/sources": { "get": { "operationId": "listCanonicalSources", "summary": "List canonical sources", "tags": [ "Canonical" ], "parameters": [ { "$ref": "#/components/parameters/TenantIdHeader" } ], "responses": { "200": { "description": "Source list", "content": { "application/json": { "schema": { "type": "object", "properties": { "sources": { "type": "array", "items": { "type": "object" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/lifecycle/status": { "get": { "operationId": "lifecycleStatus", "summary": "Document lifecycle status", "tags": [ "Lifecycle" ], "parameters": [ { "$ref": "#/components/parameters/TenantIdHeader" } ], "responses": { "200": { "description": "Lifecycle statistics", "content": { "application/json": { "schema": { "type": "object", "properties": { "active": { "type": "integer" }, "archived": { "type": "integer" }, "forgotten": { "type": "integer" }, "pinned": { "type": "integer" }, "snoozed": { "type": "integer" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/lifecycle/sweep": { "post": { "operationId": "lifecycleSweep", "summary": "Run lifecycle sweep", "description": "Archive stale docs, optionally purge old archives. Defaults to dry run.", "tags": [ "Lifecycle" ], "parameters": [ { "$ref": "#/components/parameters/TenantIdHeader" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "dry_run": { "type": "boolean", "default": true } } } } } }, "responses": { "200": { "description": "Sweep result", "content": { "application/json": { "schema": { "type": "object", "properties": { "dry_run": { "type": "boolean" }, "to_archive": { "type": "integer" }, "to_purge": { "type": "integer" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/lifecycle/restore": { "post": { "operationId": "lifecycleRestore", "summary": "Restore archived documents", "tags": [ "Lifecycle" ], "parameters": [ { "$ref": "#/components/parameters/TenantIdHeader" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "query": { "type": "string" }, "collection": { "type": "string" }, "all": { "type": "boolean", "default": false } } } } } }, "responses": { "200": { "description": "Restore result", "content": { "application/json": { "schema": { "type": "object", "properties": { "restored": { "type": "integer" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/reindex": { "post": { "operationId": "reindex", "summary": "Trigger full reindex", "description": "Re-scan all collections, detect new/changed/deleted documents.", "tags": [ "Maintenance" ], "parameters": [ { "$ref": "#/components/parameters/TenantIdHeader" } ], "responses": { "200": { "description": "Reindex initiated", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/graphs/build": { "post": { "operationId": "buildGraphs", "summary": "Build temporal and semantic graphs", "tags": [ "Maintenance" ], "parameters": [ { "$ref": "#/components/parameters/TenantIdHeader" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "graph_types": { "type": "array", "items": { "type": "string", "enum": [ "temporal", "semantic", "all" ] }, "semantic_threshold": { "type": "number", "default": 0.7 } } } } } } }, "responses": { "200": { "description": "Graph build initiated", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/api/v1/collection-settings": { "get": { "operationId": "listCollectionSettings", "summary": "List all collection settings", "tags": [ "Maintenance" ], "parameters": [ { "$ref": "#/components/parameters/TenantIdHeader" } ], "responses": { "200": { "description": "Settings list", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/api/v1/collection-settings/reindex": { "get": { "operationId": "reindexCollectionSettings", "summary": "Re-evaluate documents against quality gate rules", "tags": [ "Maintenance" ], "parameters": [ { "$ref": "#/components/parameters/TenantIdHeader" } ], "responses": { "200": { "description": "Reindex result", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "collection": { "type": "string" }, "dry_run": { "type": "boolean" }, "total_docs": { "type": "integer" }, "to_skip": { "type": "integer" }, "to_index": { "type": "integer" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } }, "post": { "operationId": "reindexCollectionSettingsPost", "summary": "Re-evaluate documents against quality gate rules (POST)", "tags": [ "Maintenance" ], "parameters": [ { "$ref": "#/components/parameters/TenantIdHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "collection" ], "properties": { "collection": { "type": "string" }, "dry_run": { "type": "boolean", "default": false } } } } } }, "responses": { "200": { "description": "Reindex result", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/api/v1/collection-settings/{collection}": { "get": { "operationId": "getCollectionSettings", "summary": "Get settings for a collection", "tags": [ "Maintenance" ], "parameters": [ { "$ref": "#/components/parameters/TenantIdHeader" }, { "name": "collection", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Collection settings", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "put": { "operationId": "setCollectionSettings", "summary": "Set settings for a collection", "tags": [ "Maintenance" ], "parameters": [ { "$ref": "#/components/parameters/TenantIdHeader" }, { "name": "collection", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "max_doc_size": { "type": "integer" }, "skip_patterns": { "type": "array", "items": { "type": "string" } }, "min_quality_score": { "type": "number" } } } } } }, "responses": { "200": { "description": "Settings updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } }, "delete": { "operationId": "deleteCollectionSettings", "summary": "Delete settings for a collection", "tags": [ "Maintenance" ], "parameters": [ { "$ref": "#/components/parameters/TenantIdHeader" }, { "name": "collection", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Settings deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/generate": { "post": { "operationId": "generate", "summary": "LLM text generation (benchmark only)", "description": "Exposes the engine's local LLM as a simple text generation API. Benchmark tooling only.", "tags": [ "Maintenance" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "prompt" ], "properties": { "prompt": { "type": "string" }, "maxTokens": { "type": "integer", "default": 512, "maximum": 2048 }, "temperature": { "type": "number", "minimum": 0, "maximum": 2 } } } } } }, "responses": { "200": { "description": "Generated text", "content": { "application/json": { "schema": { "type": "object", "properties": { "text": { "type": "string" }, "model": { "type": "string" }, "tokens": { "type": "integer" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/skills": { "get": { "operationId": "listSkills", "summary": "List registered skills", "tags": [ "Maintenance" ], "responses": { "200": { "description": "Skill list", "content": { "application/json": { "schema": { "type": "object", "properties": { "skills": { "type": "array", "items": { "type": "object" } } } } } } } } }, "post": { "operationId": "addSkill", "summary": "Register a new skill", "tags": [ "Maintenance" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "handler": { "type": "string" } } } } } }, "responses": { "200": { "description": "Skill registered", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } } } } } } } } }, "/skills/{skillId}": { "get": { "operationId": "getSkill", "summary": "Get skill details", "tags": [ "Maintenance" ], "parameters": [ { "name": "skillId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Skill details", "content": { "application/json": { "schema": { "type": "object" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/setup/instructions": { "get": { "operationId": "setupInstructions", "summary": "Get setup instructions (public)", "tags": [ "Maintenance" ], "security": [], "responses": { "200": { "description": "Setup instructions", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/admin/l0-l1/run": { "post": { "operationId": "l0l1Run", "summary": "Trigger L0/L1 generation", "tags": [ "Admin" ], "responses": { "200": { "description": "L0/L1 generation initiated", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } } } } } } } } }, "/export": { "get": { "operationId": "exportData", "summary": "Export documents", "tags": [ "Documents" ], "parameters": [ { "$ref": "#/components/parameters/TenantIdHeader" }, { "name": "collection", "in": "query", "schema": { "type": "string" } }, { "name": "format", "in": "query", "schema": { "type": "string", "enum": [ "json", "markdown" ], "default": "json" } } ], "responses": { "200": { "description": "Exported data", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/openapi.json": { "get": { "operationId": "openapiSpec", "summary": "OpenAPI 3.1 specification (JSON)", "description": "Returns the full API specification as JSON.", "tags": [ "Health" ], "security": [], "responses": { "200": { "description": "OpenAPI specification", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/openapi.yaml": { "get": { "tags": [ "Runtime" ], "summary": "Registered on this process; not yet in docs/reference/openapi.yaml", "operationId": "live_GET__openapi_yaml", "x-valorbrain-live": true, "responses": { "200": { "description": "See the running handler" } } } }, "/health/admin": { "get": { "tags": [ "Runtime" ], "summary": "Registered on this process; not yet in docs/reference/openapi.yaml", "operationId": "live_GET__health_admin", "x-valorbrain-live": true, "responses": { "200": { "description": "See the running handler" } } } }, "/reports/usage": { "get": { "tags": [ "Runtime" ], "summary": "Registered on this process; not yet in docs/reference/openapi.yaml", "operationId": "live_GET__reports_usage", "x-valorbrain-live": true, "responses": { "200": { "description": "See the running handler" } } } }, "/api/v1/memory/team-activity": { "get": { "tags": [ "Runtime" ], "summary": "Registered on this process; not yet in docs/reference/openapi.yaml", "operationId": "live_GET__api_v1_memory_team_activity", "x-valorbrain-live": true, "responses": { "200": { "description": "See the running handler" } } } }, "/dashboard": { "get": { "tags": [ "Runtime" ], "summary": "Registered on this process; not yet in docs/reference/openapi.yaml", "operationId": "live_GET__dashboard", "x-valorbrain-live": true, "responses": { "200": { "description": "See the running handler" } } } }, "/memory-map": { "get": { "tags": [ "Runtime" ], "summary": "Registered on this process; not yet in docs/reference/openapi.yaml", "operationId": "live_GET__memory_map", "x-valorbrain-live": true, "responses": { "200": { "description": "See the running handler" } } } }, "/api/v1/knowledge-gaps": { "get": { "tags": [ "Runtime" ], "summary": "Registered on this process; not yet in docs/reference/openapi.yaml", "operationId": "live_GET__api_v1_knowledge_gaps", "x-valorbrain-live": true, "responses": { "200": { "description": "See the running handler" } } } }, "/api/v1/knowledge-gaps/{id}/resolve": { "post": { "tags": [ "Runtime" ], "summary": "Registered on this process; not yet in docs/reference/openapi.yaml", "operationId": "live_POST__api_v1_knowledge_gaps_id_resolve", "x-valorbrain-live": true, "responses": { "200": { "description": "See the running handler" } } } }, "/conversations": { "post": { "tags": [ "Runtime" ], "summary": "Registered on this process; not yet in docs/reference/openapi.yaml", "operationId": "live_POST__conversations", "x-valorbrain-live": true, "responses": { "200": { "description": "See the running handler" } } } }, "/harness-coverage": { "get": { "tags": [ "Runtime" ], "summary": "Registered on this process; not yet in docs/reference/openapi.yaml", "operationId": "live_GET__harness_coverage", "x-valorbrain-live": true, "responses": { "200": { "description": "See the running handler" } } } }, "/contradictions": { "get": { "tags": [ "Runtime" ], "summary": "Registered on this process; not yet in docs/reference/openapi.yaml", "operationId": "live_GET__contradictions", "x-valorbrain-live": true, "responses": { "200": { "description": "See the running handler" } } } }, "/documents/changes": { "get": { "tags": [ "Runtime" ], "summary": "Registered on this process; not yet in docs/reference/openapi.yaml", "operationId": "live_GET__documents_changes", "x-valorbrain-live": true, "responses": { "200": { "description": "See the running handler" } } } }, "/documents/{id}/chain": { "get": { "tags": [ "Runtime" ], "summary": "Registered on this process; not yet in docs/reference/openapi.yaml", "operationId": "live_GET__documents_id_chain", "x-valorbrain-live": true, "responses": { "200": { "description": "See the running handler" } } } }, "/documents/{id}/veracity": { "patch": { "tags": [ "Runtime" ], "summary": "Registered on this process; not yet in docs/reference/openapi.yaml", "operationId": "live_PATCH__documents_id_veracity", "x-valorbrain-live": true, "responses": { "200": { "description": "See the running handler" } } } }, "/api/v1/documents/{id}/veracity": { "patch": { "tags": [ "Runtime" ], "summary": "Registered on this process; not yet in docs/reference/openapi.yaml", "operationId": "live_PATCH__api_v1_documents_id_veracity", "x-valorbrain-live": true, "responses": { "200": { "description": "See the running handler" } } } }, "/documents/veracity/bulk": { "patch": { "tags": [ "Runtime" ], "summary": "Registered on this process; not yet in docs/reference/openapi.yaml", "operationId": "live_PATCH__documents_veracity_bulk", "x-valorbrain-live": true, "responses": { "200": { "description": "See the running handler" } } } }, "/api/v1/documents/veracity/bulk": { "patch": { "tags": [ "Runtime" ], "summary": "Registered on this process; not yet in docs/reference/openapi.yaml", "operationId": "live_PATCH__api_v1_documents_veracity_bulk", "x-valorbrain-live": true, "responses": { "200": { "description": "See the running handler" } } } }, "/collections/health": { "get": { "tags": [ "Runtime" ], "summary": "Registered on this process; not yet in docs/reference/openapi.yaml", "operationId": "live_GET__collections_health", "x-valorbrain-live": true, "responses": { "200": { "description": "See the running handler" } } } }, "/collections/{id}/lifecycle": { "post": { "tags": [ "Runtime" ], "summary": "Registered on this process; not yet in docs/reference/openapi.yaml", "operationId": "live_POST__collections_id_lifecycle", "x-valorbrain-live": true, "responses": { "200": { "description": "See the running handler" } } } }, "/api/v1/memory/working-context": { "get": { "tags": [ "Runtime" ], "summary": "Registered on this process; not yet in docs/reference/openapi.yaml", "operationId": "live_GET__api_v1_memory_working_context", "x-valorbrain-live": true, "responses": { "200": { "description": "See the running handler" } } } }, "/memory/working-context": { "get": { "tags": [ "Runtime" ], "summary": "Registered on this process; not yet in docs/reference/openapi.yaml", "operationId": "live_GET__memory_working_context", "x-valorbrain-live": true, "responses": { "200": { "description": "See the running handler" } } } }, "/api/v1/scratchpad": { "get": { "tags": [ "Runtime" ], "summary": "Registered on this process; not yet in docs/reference/openapi.yaml", "operationId": "live_GET__api_v1_scratchpad", "x-valorbrain-live": true, "responses": { "200": { "description": "See the running handler" } } }, "put": { "tags": [ "Runtime" ], "summary": "Registered on this process; not yet in docs/reference/openapi.yaml", "operationId": "live_PUT__api_v1_scratchpad", "x-valorbrain-live": true, "responses": { "200": { "description": "See the running handler" } } }, "post": { "tags": [ "Runtime" ], "summary": "Registered on this process; not yet in docs/reference/openapi.yaml", "operationId": "live_POST__api_v1_scratchpad", "x-valorbrain-live": true, "responses": { "200": { "description": "See the running handler" } } }, "delete": { "tags": [ "Runtime" ], "summary": "Registered on this process; not yet in docs/reference/openapi.yaml", "operationId": "live_DELETE__api_v1_scratchpad", "x-valorbrain-live": true, "responses": { "200": { "description": "See the running handler" } } } }, "/scratchpad": { "get": { "tags": [ "Runtime" ], "summary": "Registered on this process; not yet in docs/reference/openapi.yaml", "operationId": "live_GET__scratchpad", "x-valorbrain-live": true, "responses": { "200": { "description": "See the running handler" } } }, "put": { "tags": [ "Runtime" ], "summary": "Registered on this process; not yet in docs/reference/openapi.yaml", "operationId": "live_PUT__scratchpad", "x-valorbrain-live": true, "responses": { "200": { "description": "See the running handler" } } }, "post": { "tags": [ "Runtime" ], "summary": "Registered on this process; not yet in docs/reference/openapi.yaml", "operationId": "live_POST__scratchpad", "x-valorbrain-live": true, "responses": { "200": { "description": "See the running handler" } } }, "delete": { "tags": [ "Runtime" ], "summary": "Registered on this process; not yet in docs/reference/openapi.yaml", "operationId": "live_DELETE__scratchpad", "x-valorbrain-live": true, "responses": { "200": { "description": "See the running handler" } } } }, "/setup/artifacts": { "get": { "tags": [ "Runtime" ], "summary": "Registered on this process; not yet in docs/reference/openapi.yaml", "operationId": "live_GET__setup_artifacts", "x-valorbrain-live": true, "responses": { "200": { "description": "See the running handler" } } } }, "/api/v1/entity-cards": { "get": { "tags": [ "Runtime" ], "summary": "Registered on this process; not yet in docs/reference/openapi.yaml", "operationId": "live_GET__api_v1_entity_cards", "x-valorbrain-live": true, "responses": { "200": { "description": "See the running handler" } } } }, "/api/v1/feedback": { "post": { "tags": [ "Runtime" ], "summary": "Registered on this process; not yet in docs/reference/openapi.yaml", "operationId": "live_POST__api_v1_feedback", "x-valorbrain-live": true, "responses": { "200": { "description": "See the running handler" } } } }, "/api/v1/secrets": { "get": { "tags": [ "Runtime" ], "summary": "Registered on this process; not yet in docs/reference/openapi.yaml", "operationId": "live_GET__api_v1_secrets", "x-valorbrain-live": true, "responses": { "200": { "description": "See the running handler" } } }, "post": { "tags": [ "Runtime" ], "summary": "Registered on this process; not yet in docs/reference/openapi.yaml", "operationId": "live_POST__api_v1_secrets", "x-valorbrain-live": true, "responses": { "200": { "description": "See the running handler" } } } }, "/api/v1/pins": { "get": { "tags": [ "Runtime" ], "summary": "Registered on this process; not yet in docs/reference/openapi.yaml", "operationId": "live_GET__api_v1_pins", "x-valorbrain-live": true, "responses": { "200": { "description": "See the running handler" } } }, "post": { "tags": [ "Runtime" ], "summary": "Registered on this process; not yet in docs/reference/openapi.yaml", "operationId": "live_POST__api_v1_pins", "x-valorbrain-live": true, "responses": { "200": { "description": "See the running handler" } } } }, "/api/v1/pins/{id}": { "get": { "tags": [ "Runtime" ], "summary": "Registered on this process; not yet in docs/reference/openapi.yaml", "operationId": "live_GET__api_v1_pins_id_", "x-valorbrain-live": true, "responses": { "200": { "description": "See the running handler" } } }, "patch": { "tags": [ "Runtime" ], "summary": "Registered on this process; not yet in docs/reference/openapi.yaml", "operationId": "live_PATCH__api_v1_pins_id_", "x-valorbrain-live": true, "responses": { "200": { "description": "See the running handler" } } }, "delete": { "tags": [ "Runtime" ], "summary": "Registered on this process; not yet in docs/reference/openapi.yaml", "operationId": "live_DELETE__api_v1_pins_id_", "x-valorbrain-live": true, "responses": { "200": { "description": "See the running handler" } } } }, "/api/v1/session-handoffs": { "post": { "tags": [ "Runtime" ], "summary": "Registered on this process; not yet in docs/reference/openapi.yaml", "operationId": "live_POST__api_v1_session_handoffs", "x-valorbrain-live": true, "responses": { "200": { "description": "See the running handler" } } }, "get": { "tags": [ "Runtime" ], "summary": "Registered on this process; not yet in docs/reference/openapi.yaml", "operationId": "live_GET__api_v1_session_handoffs", "x-valorbrain-live": true, "responses": { "200": { "description": "See the running handler" } } } }, "/api/v1/team/members": { "get": { "tags": [ "Runtime" ], "summary": "Registered on this process; not yet in docs/reference/openapi.yaml", "operationId": "live_GET__api_v1_team_members", "x-valorbrain-live": true, "responses": { "200": { "description": "See the running handler" } } } }, "/api/v1/team/overview": { "get": { "tags": [ "Runtime" ], "summary": "Registered on this process; not yet in docs/reference/openapi.yaml", "operationId": "live_GET__api_v1_team_overview", "x-valorbrain-live": true, "responses": { "200": { "description": "See the running handler" } } } }, "/api/v1/task-state": { "get": { "tags": [ "Runtime" ], "summary": "Registered on this process; not yet in docs/reference/openapi.yaml", "operationId": "live_GET__api_v1_task_state", "x-valorbrain-live": true, "responses": { "200": { "description": "See the running handler" } } } }, "/api/v1/team/messages": { "post": { "tags": [ "Runtime" ], "summary": "Registered on this process; not yet in docs/reference/openapi.yaml", "operationId": "live_POST__api_v1_team_messages", "x-valorbrain-live": true, "responses": { "200": { "description": "See the running handler" } } } }, "/api/v1/team/inbox": { "get": { "tags": [ "Runtime" ], "summary": "Registered on this process; not yet in docs/reference/openapi.yaml", "operationId": "live_GET__api_v1_team_inbox", "x-valorbrain-live": true, "responses": { "200": { "description": "See the running handler" } } } }, "/api/v1/team/handoffs": { "post": { "tags": [ "Runtime" ], "summary": "Registered on this process; not yet in docs/reference/openapi.yaml", "operationId": "live_POST__api_v1_team_handoffs", "x-valorbrain-live": true, "responses": { "200": { "description": "See the running handler" } } }, "get": { "tags": [ "Runtime" ], "summary": "Registered on this process; not yet in docs/reference/openapi.yaml", "operationId": "live_GET__api_v1_team_handoffs", "x-valorbrain-live": true, "responses": { "200": { "description": "See the running handler" } } } }, "/api/v1/team/briefing": { "get": { "tags": [ "Runtime" ], "summary": "Registered on this process; not yet in docs/reference/openapi.yaml", "operationId": "live_GET__api_v1_team_briefing", "x-valorbrain-live": true, "responses": { "200": { "description": "See the running handler" } } } }, "/api/v1/team/stream": { "get": { "tags": [ "Runtime" ], "summary": "Registered on this process; not yet in docs/reference/openapi.yaml", "operationId": "live_GET__api_v1_team_stream", "x-valorbrain-live": true, "responses": { "200": { "description": "See the running handler" } } } }, "/api/v1/memory/episodes": { "get": { "tags": [ "Runtime" ], "summary": "Registered on this process; not yet in docs/reference/openapi.yaml", "operationId": "live_GET__api_v1_memory_episodes", "x-valorbrain-live": true, "responses": { "200": { "description": "See the running handler" } } } }, "/api/v1/memory/episodes/{id}": { "get": { "tags": [ "Runtime" ], "summary": "Registered on this process; not yet in docs/reference/openapi.yaml", "operationId": "live_GET__api_v1_memory_episodes_id_", "x-valorbrain-live": true, "responses": { "200": { "description": "See the running handler" } } } }, "/admin/queues": { "get": { "tags": [ "Runtime" ], "summary": "Registered on this process; not yet in docs/reference/openapi.yaml", "operationId": "live_GET__admin_queues", "x-valorbrain-live": true, "responses": { "200": { "description": "See the running handler" } } }, "post": { "tags": [ "Runtime" ], "summary": "Registered on this process; not yet in docs/reference/openapi.yaml", "operationId": "live_POST__admin_queues", "x-valorbrain-live": true, "responses": { "200": { "description": "See the running handler" } } } }, "/api/v1/admin/tenants/{id}/api-tokens": { "post": { "tags": [ "Runtime" ], "summary": "Registered on this process; not yet in docs/reference/openapi.yaml", "operationId": "live_POST__api_v1_admin_tenants_id_api_tokens", "x-valorbrain-live": true, "responses": { "200": { "description": "See the running handler" } } }, "get": { "tags": [ "Runtime" ], "summary": "Registered on this process; not yet in docs/reference/openapi.yaml", "operationId": "live_GET__api_v1_admin_tenants_id_api_tokens", "x-valorbrain-live": true, "responses": { "200": { "description": "See the running handler" } } } }, "/api/v1/admin/tenants/{id}/api-tokens/{id2}": { "delete": { "tags": [ "Runtime" ], "summary": "Registered on this process; not yet in docs/reference/openapi.yaml", "operationId": "live_DELETE__api_v1_admin_tenants_id_api_tokens_id2_", "x-valorbrain-live": true, "responses": { "200": { "description": "See the running handler" } } } }, "/api/v1/admin/tenants/{id}/status": { "patch": { "tags": [ "Runtime" ], "summary": "Registered on this process; not yet in docs/reference/openapi.yaml", "operationId": "live_PATCH__api_v1_admin_tenants_id_status", "x-valorbrain-live": true, "responses": { "200": { "description": "See the running handler" } } } }, "/api/v1/memory/refine": { "post": { "tags": [ "Runtime" ], "summary": "Registered on this process; not yet in docs/reference/openapi.yaml", "operationId": "live_POST__api_v1_memory_refine", "x-valorbrain-live": true, "responses": { "200": { "description": "See the running handler" } } } }, "/api/v1/runtimes/register": { "post": { "tags": [ "Runtime" ], "summary": "Registered on this process; not yet in docs/reference/openapi.yaml", "operationId": "live_POST__api_v1_runtimes_register", "x-valorbrain-live": true, "responses": { "200": { "description": "See the running handler" } } } }, "/api/v1/runtimes/heartbeat": { "post": { "tags": [ "Runtime" ], "summary": "Registered on this process; not yet in docs/reference/openapi.yaml", "operationId": "live_POST__api_v1_runtimes_heartbeat", "x-valorbrain-live": true, "responses": { "200": { "description": "See the running handler" } } } }, "/api/v1/runtimes": { "get": { "tags": [ "Runtime" ], "summary": "Registered on this process; not yet in docs/reference/openapi.yaml", "operationId": "live_GET__api_v1_runtimes", "x-valorbrain-live": true, "responses": { "200": { "description": "See the running handler" } } } }, "/api/v1/kg/explore": { "get": { "tags": [ "Runtime" ], "summary": "Registered on this process; not yet in docs/reference/openapi.yaml", "operationId": "live_GET__api_v1_kg_explore", "x-valorbrain-live": true, "responses": { "200": { "description": "See the running handler" } } } }, "/api/v1/kg/entity-documents": { "get": { "tags": [ "Runtime" ], "summary": "Registered on this process; not yet in docs/reference/openapi.yaml", "operationId": "live_GET__api_v1_kg_entity_documents", "x-valorbrain-live": true, "responses": { "200": { "description": "See the running handler" } } } }, "/api/v1/memory/store": { "post": { "tags": [ "Runtime" ], "summary": "Registered on this process; not yet in docs/reference/openapi.yaml", "operationId": "live_POST__api_v1_memory_store", "x-valorbrain-live": true, "responses": { "200": { "description": "See the running handler" } } } }, "/api/v1/memory/confirm-sample": { "get": { "tags": [ "Runtime" ], "summary": "Registered on this process; not yet in docs/reference/openapi.yaml", "operationId": "live_GET__api_v1_memory_confirm_sample", "x-valorbrain-live": true, "responses": { "200": { "description": "See the running handler" } } } }, "/api/v1/tenant/trust-summary": { "get": { "tags": [ "Runtime" ], "summary": "Registered on this process; not yet in docs/reference/openapi.yaml", "operationId": "live_GET__api_v1_tenant_trust_summary", "x-valorbrain-live": true, "responses": { "200": { "description": "See the running handler" } } } }, "/api/v1/tenant/perf-summary": { "get": { "tags": [ "Runtime" ], "summary": "Registered on this process; not yet in docs/reference/openapi.yaml", "operationId": "live_GET__api_v1_tenant_perf_summary", "x-valorbrain-live": true, "responses": { "200": { "description": "See the running handler" } } } }, "/api/v1/tenant/impact": { "get": { "tags": [ "Runtime" ], "summary": "Registered on this process; not yet in docs/reference/openapi.yaml", "operationId": "live_GET__api_v1_tenant_impact", "x-valorbrain-live": true, "responses": { "200": { "description": "See the running handler" } } } }, "/api/v1/users/resolve-caller": { "post": { "tags": [ "Runtime" ], "summary": "Registered on this process; not yet in docs/reference/openapi.yaml", "operationId": "live_POST__api_v1_users_resolve_caller", "x-valorbrain-live": true, "responses": { "200": { "description": "See the running handler" } } } }, "/api/v1/users/channel-identities": { "get": { "tags": [ "Runtime" ], "summary": "Registered on this process; not yet in docs/reference/openapi.yaml", "operationId": "live_GET__api_v1_users_channel_identities", "x-valorbrain-live": true, "responses": { "200": { "description": "See the running handler" } } }, "post": { "tags": [ "Runtime" ], "summary": "Registered on this process; not yet in docs/reference/openapi.yaml", "operationId": "live_POST__api_v1_users_channel_identities", "x-valorbrain-live": true, "responses": { "200": { "description": "See the running handler" } } } }, "/api/v1/audit/pubkey": { "get": { "tags": [ "Runtime" ], "summary": "Registered on this process; not yet in docs/reference/openapi.yaml", "operationId": "live_GET__api_v1_audit_pubkey", "x-valorbrain-live": true, "responses": { "200": { "description": "See the running handler" } } } }, "/api/v1/audit/bundle": { "get": { "tags": [ "Runtime" ], "summary": "Registered on this process; not yet in docs/reference/openapi.yaml", "operationId": "live_GET__api_v1_audit_bundle", "x-valorbrain-live": true, "responses": { "200": { "description": "See the running handler" } } } }, "/api/v1/audit/status": { "get": { "tags": [ "Runtime" ], "summary": "Registered on this process; not yet in docs/reference/openapi.yaml", "operationId": "live_GET__api_v1_audit_status", "x-valorbrain-live": true, "responses": { "200": { "description": "See the running handler" } } } }, "/api/v1/audit/recent": { "get": { "tags": [ "Runtime" ], "summary": "Registered on this process; not yet in docs/reference/openapi.yaml", "operationId": "live_GET__api_v1_audit_recent", "x-valorbrain-live": true, "responses": { "200": { "description": "See the running handler" } } } }, "/api/v1/read-log/summary": { "get": { "tags": [ "Runtime" ], "summary": "Registered on this process; not yet in docs/reference/openapi.yaml", "operationId": "live_GET__api_v1_read_log_summary", "x-valorbrain-live": true, "responses": { "200": { "description": "See the running handler" } } } }, "/api/v1/lessons": { "get": { "tags": [ "Runtime" ], "summary": "Registered on this process; not yet in docs/reference/openapi.yaml", "operationId": "live_GET__api_v1_lessons", "x-valorbrain-live": true, "responses": { "200": { "description": "See the running handler" } } } }, "/api/v1/lessons/record": { "post": { "tags": [ "Runtime" ], "summary": "Registered on this process; not yet in docs/reference/openapi.yaml", "operationId": "live_POST__api_v1_lessons_record", "x-valorbrain-live": true, "responses": { "200": { "description": "See the running handler" } } } }, "/api/v1/lessons/feedback": { "post": { "tags": [ "Runtime" ], "summary": "Registered on this process; not yet in docs/reference/openapi.yaml", "operationId": "live_POST__api_v1_lessons_feedback", "x-valorbrain-live": true, "responses": { "200": { "description": "See the running handler" } } } }, "/api/v1/arcs": { "get": { "tags": [ "Runtime" ], "summary": "Registered on this process; not yet in docs/reference/openapi.yaml", "operationId": "live_GET__api_v1_arcs", "x-valorbrain-live": true, "responses": { "200": { "description": "See the running handler" } } }, "post": { "tags": [ "Runtime" ], "summary": "Registered on this process; not yet in docs/reference/openapi.yaml", "operationId": "live_POST__api_v1_arcs", "x-valorbrain-live": true, "responses": { "200": { "description": "See the running handler" } } } }, "/api/v1/keyed-facts/as-of": { "get": { "tags": [ "Runtime" ], "summary": "Registered on this process; not yet in docs/reference/openapi.yaml", "operationId": "live_GET__api_v1_keyed_facts_as_of", "x-valorbrain-live": true, "responses": { "200": { "description": "See the running handler" } } } }, "/api/v1/keyed-facts": { "post": { "tags": [ "Runtime" ], "summary": "Registered on this process; not yet in docs/reference/openapi.yaml", "operationId": "live_POST__api_v1_keyed_facts", "x-valorbrain-live": true, "responses": { "200": { "description": "See the running handler" } } } }, "/api/v1/keyed-facts/correct": { "post": { "tags": [ "Runtime" ], "summary": "Registered on this process; not yet in docs/reference/openapi.yaml", "operationId": "live_POST__api_v1_keyed_facts_correct", "x-valorbrain-live": true, "responses": { "200": { "description": "See the running handler" } } } }, "/api/v1/authority/mandates": { "post": { "tags": [ "Runtime" ], "summary": "Registered on this process; not yet in docs/reference/openapi.yaml", "operationId": "live_POST__api_v1_authority_mandates", "x-valorbrain-live": true, "responses": { "200": { "description": "See the running handler" } } }, "get": { "tags": [ "Runtime" ], "summary": "Registered on this process; not yet in docs/reference/openapi.yaml", "operationId": "live_GET__api_v1_authority_mandates", "x-valorbrain-live": true, "responses": { "200": { "description": "See the running handler" } } } }, "/api/v1/harness-integrations": { "post": { "tags": [ "Runtime" ], "summary": "Registered on this process; not yet in docs/reference/openapi.yaml", "operationId": "live_POST__api_v1_harness_integrations", "x-valorbrain-live": true, "responses": { "200": { "description": "See the running handler" } } }, "get": { "tags": [ "Runtime" ], "summary": "Registered on this process; not yet in docs/reference/openapi.yaml", "operationId": "live_GET__api_v1_harness_integrations", "x-valorbrain-live": true, "responses": { "200": { "description": "See the running handler" } } } }, "/api/v1/memory/prepare": { "post": { "tags": [ "Runtime" ], "summary": "Registered on this process; not yet in docs/reference/openapi.yaml", "operationId": "live_POST__api_v1_memory_prepare", "x-valorbrain-live": true, "responses": { "200": { "description": "See the running handler" } } } }, "/api/v1/kg/quarantine": { "get": { "tags": [ "Runtime" ], "summary": "Registered on this process; not yet in docs/reference/openapi.yaml", "operationId": "live_GET__api_v1_kg_quarantine", "x-valorbrain-live": true, "responses": { "200": { "description": "See the running handler" } } } }, "/api/v1/kg/entity-resolve/report": { "get": { "tags": [ "Runtime" ], "summary": "Registered on this process; not yet in docs/reference/openapi.yaml", "operationId": "live_GET__api_v1_kg_entity_resolve_report", "x-valorbrain-live": true, "responses": { "200": { "description": "See the running handler" } } } }, "/api/v1/kg/rag-retrieve": { "post": { "tags": [ "Runtime" ], "summary": "Registered on this process; not yet in docs/reference/openapi.yaml", "operationId": "live_POST__api_v1_kg_rag_retrieve", "x-valorbrain-live": true, "responses": { "200": { "description": "See the running handler" } } } }, "/api/v1/usage/answers": { "get": { "tags": [ "Runtime" ], "summary": "Registered on this process; not yet in docs/reference/openapi.yaml", "operationId": "live_GET__api_v1_usage_answers", "x-valorbrain-live": true, "responses": { "200": { "description": "See the running handler" } } } }, "/api/v1/credits/summary": { "get": { "tags": [ "Runtime" ], "summary": "Registered on this process; not yet in docs/reference/openapi.yaml", "operationId": "live_GET__api_v1_credits_summary", "x-valorbrain-live": true, "responses": { "200": { "description": "See the running handler" } } } }, "/api/v1/session-bootstrap": { "post": { "tags": [ "Runtime" ], "summary": "Registered on this process; not yet in docs/reference/openapi.yaml", "operationId": "live_POST__api_v1_session_bootstrap", "x-valorbrain-live": true, "responses": { "200": { "description": "See the running handler" } } } }, "/api/v1/hooks/run": { "post": { "tags": [ "Runtime" ], "summary": "Registered on this process; not yet in docs/reference/openapi.yaml", "operationId": "live_POST__api_v1_hooks_run", "x-valorbrain-live": true, "responses": { "200": { "description": "See the running handler" } } } }, "/api/v1/decisions": { "post": { "tags": [ "Runtime" ], "summary": "Registered on this process; not yet in docs/reference/openapi.yaml", "operationId": "live_POST__api_v1_decisions", "x-valorbrain-live": true, "responses": { "200": { "description": "See the running handler" } } }, "get": { "tags": [ "Runtime" ], "summary": "Registered on this process; not yet in docs/reference/openapi.yaml", "operationId": "live_GET__api_v1_decisions", "x-valorbrain-live": true, "responses": { "200": { "description": "See the running handler" } } } }, "/api/v1/decisions/relations": { "post": { "tags": [ "Runtime" ], "summary": "Registered on this process; not yet in docs/reference/openapi.yaml", "operationId": "live_POST__api_v1_decisions_relations", "x-valorbrain-live": true, "responses": { "200": { "description": "See the running handler" } } } }, "/api/v1/decisions/chain": { "get": { "tags": [ "Runtime" ], "summary": "Registered on this process; not yet in docs/reference/openapi.yaml", "operationId": "live_GET__api_v1_decisions_chain", "x-valorbrain-live": true, "responses": { "200": { "description": "See the running handler" } } } }, "/api/v1/decisions/similar": { "get": { "tags": [ "Runtime" ], "summary": "Registered on this process; not yet in docs/reference/openapi.yaml", "operationId": "live_GET__api_v1_decisions_similar", "x-valorbrain-live": true, "responses": { "200": { "description": "See the running handler" } } } }, "/api/v1/decisions/impact": { "get": { "tags": [ "Runtime" ], "summary": "Registered on this process; not yet in docs/reference/openapi.yaml", "operationId": "live_GET__api_v1_decisions_impact", "x-valorbrain-live": true, "responses": { "200": { "description": "See the running handler" } } } }, "/api/v1/provenance": { "post": { "tags": [ "Runtime" ], "summary": "Registered on this process; not yet in docs/reference/openapi.yaml", "operationId": "live_POST__api_v1_provenance", "x-valorbrain-live": true, "responses": { "200": { "description": "See the running handler" } } } }, "/api/v1/provenance/lineage": { "get": { "tags": [ "Runtime" ], "summary": "Registered on this process; not yet in docs/reference/openapi.yaml", "operationId": "live_GET__api_v1_provenance_lineage", "x-valorbrain-live": true, "responses": { "200": { "description": "See the running handler" } } } }, "/api/v1/provenance/export": { "get": { "tags": [ "Runtime" ], "summary": "Registered on this process; not yet in docs/reference/openapi.yaml", "operationId": "live_GET__api_v1_provenance_export", "x-valorbrain-live": true, "responses": { "200": { "description": "See the running handler" } } } }, "/api/v1/provenance/verify": { "get": { "tags": [ "Runtime" ], "summary": "Registered on this process; not yet in docs/reference/openapi.yaml", "operationId": "live_GET__api_v1_provenance_verify", "x-valorbrain-live": true, "responses": { "200": { "description": "See the running handler" } } } }, "/api/v1/conflicts/detect": { "post": { "tags": [ "Runtime" ], "summary": "Registered on this process; not yet in docs/reference/openapi.yaml", "operationId": "live_POST__api_v1_conflicts_detect", "x-valorbrain-live": true, "responses": { "200": { "description": "See the running handler" } } } }, "/api/v1/fact-conflicts": { "get": { "tags": [ "Runtime" ], "summary": "Registered on this process; not yet in docs/reference/openapi.yaml", "operationId": "live_GET__api_v1_fact_conflicts", "x-valorbrain-live": true, "responses": { "200": { "description": "See the running handler" } } } }, "/api/v1/conflicts/resolve": { "post": { "tags": [ "Runtime" ], "summary": "Registered on this process; not yet in docs/reference/openapi.yaml", "operationId": "live_POST__api_v1_conflicts_resolve", "x-valorbrain-live": true, "responses": { "200": { "description": "See the running handler" } } } }, "/api/v1/contradictions": { "get": { "tags": [ "Runtime" ], "summary": "Registered on this process; not yet in docs/reference/openapi.yaml", "operationId": "live_GET__api_v1_contradictions", "x-valorbrain-live": true, "responses": { "200": { "description": "See the running handler" } } } }, "/api/v1/contradictions/{n}/resolve": { "post": { "tags": [ "Runtime" ], "summary": "Registered on this process; not yet in docs/reference/openapi.yaml", "operationId": "live_POST__api_v1_contradictions_n_resolve", "x-valorbrain-live": true, "responses": { "200": { "description": "See the running handler" } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "VALORBRAIN_API_TOKEN or shadow tenant API key (vb_*)" }, "adminSecret": { "type": "apiKey", "in": "header", "name": "Authorization", "description": "ENGINE_ADMIN_SECRET as Bearer token" }, "moneyAdminAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "VALORBRAIN_API_TOKEN or ENGINE_ADMIN_SECRET", "description": "Money-route credential. Accepts the engine master token or ENGINE_ADMIN_SECRET. Tenant API and MCP persona tokens are rejected.\n" } }, "parameters": { "TenantIdHeader": { "name": "X-Tenant-ID", "in": "header", "required": false, "description": "Tenant UUID for multi-tenant operations. Required when VALORBRAIN_DEFAULT_TENANT_ID is not set. Some endpoints (like ingest) always require it.\n", "schema": { "type": "string", "format": "uuid" } }, "MoneyTenantIdHeader": { "name": "X-Tenant-ID", "in": "header", "required": true, "description": "Explicit target tenant UUID for a money operation. The tenant is never accepted from the JSON body.\n", "schema": { "type": "string", "format": "uuid" } } }, "responses": { "BadRequest": { "description": "Invalid request parameters or body", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "Unauthorized": { "description": "Missing or invalid authentication", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "Forbidden": { "description": "Insufficient permissions (admin required)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "NotFound": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "BillingConflict": { "description": "Source idempotency, settlement proof, provider identity, or subscription period/state conflict. Cross-tenant ownership is never disclosed.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BillingEventErrorResponse" } } } }, "BillingUnprocessable": { "description": "Recognized billing event that cannot be applied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BillingEventErrorResponse" } } } } }, "schemas": { "Document": { "type": "object", "properties": { "id": { "type": "integer", "description": "Internal document ID" }, "hash": { "type": "string", "description": "Content hash (SHA-256)" }, "collection": { "type": "string" }, "path": { "type": "string" }, "title": { "type": "string" }, "content_type": { "type": "string" }, "page_type": { "type": "string" }, "visibility": { "type": "string", "enum": [ "private", "tenant", "public" ] }, "embed_state": { "type": "string", "enum": [ "pending", "indexed", "skipped", "error" ] }, "is_pinned": { "type": "integer" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "SearchResult": { "type": "object", "properties": { "docid": { "type": "string" }, "filepath": { "type": "string" }, "title": { "type": "string" }, "score": { "type": "number" }, "snippet": { "type": "string" }, "body": { "type": "string" } } }, "ErrorResponse": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } }, "CreditBalance": { "type": "object", "properties": { "balance": { "type": "number" }, "currency": { "type": "string" } } }, "RequestContext": { "type": "object", "properties": { "tenantId": { "type": "string", "nullable": true }, "sourceAgent": { "type": "string", "nullable": true }, "sourceSystem": { "type": "string", "nullable": true }, "sessionId": { "type": "string", "nullable": true } } }, "BillingEventKind": { "type": "string", "enum": [ "subscription_activation", "subscription_renewal", "subscription_payment_failed", "subscription_cancelled", "credit_grant", "refund", "reversal" ] }, "BillingEventApplyRequest": { "type": "object", "additionalProperties": false, "required": [ "source", "source_id", "event_kind" ], "description": "All four subscription events require provider_subscription_id, period_start, and period_end. Activation and renewal additionally require plan_id and the complete settlement bundle. Their paid period is compared by PostgreSQL without JavaScript timestamp rounding. credit_amount must be zero for every event except credit_grant, where it must be positive. Refund and reversal are recognized but return unsupported_billing_event (422).\n", "allOf": [ { "oneOf": [ { "properties": { "period_start": { "type": "null" }, "period_end": { "type": "null" } } }, { "required": [ "period_start", "period_end" ], "properties": { "period_start": { "type": "string", "format": "date-time" }, "period_end": { "type": "string", "format": "date-time" } } } ] }, { "oneOf": [ { "properties": { "settlement_asset": { "type": "null" }, "settlement_network": { "type": "null" }, "settlement_amount_atomic": { "type": "null" }, "settlement_decimals": { "type": "null" }, "settlement_reference": { "type": "null" } } }, { "required": [ "settlement_asset", "settlement_network", "settlement_amount_atomic", "settlement_decimals", "settlement_reference" ], "properties": { "settlement_asset": { "type": "string", "minLength": 1 }, "settlement_network": { "type": "string", "minLength": 1 }, "settlement_amount_atomic": { "oneOf": [ { "type": "string", "pattern": "^[0-9]{1,38}$" }, { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } ] }, "settlement_decimals": { "type": "integer", "minimum": 0, "maximum": 18 }, "settlement_reference": { "type": "string", "minLength": 1 } } } ] }, { "if": { "properties": { "event_kind": { "enum": [ "subscription_activation", "subscription_renewal", "subscription_payment_failed", "subscription_cancelled" ] } }, "required": [ "event_kind" ] }, "then": { "required": [ "provider_subscription_id", "period_start", "period_end" ], "properties": { "provider_subscription_id": { "type": "string", "minLength": 1 }, "period_start": { "type": "string", "format": "date-time" }, "period_end": { "type": "string", "format": "date-time" } } } }, { "if": { "properties": { "event_kind": { "enum": [ "subscription_activation", "subscription_renewal" ] } }, "required": [ "event_kind" ] }, "then": { "required": [ "plan_id", "settlement_asset", "settlement_network", "settlement_amount_atomic", "settlement_decimals", "settlement_reference" ], "properties": { "plan_id": { "type": "string", "minLength": 1 }, "settlement_asset": { "type": "string", "minLength": 1 }, "settlement_network": { "type": "string", "minLength": 1 }, "settlement_amount_atomic": { "oneOf": [ { "type": "string", "pattern": "^[0-9]{1,38}$" }, { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } ] }, "settlement_decimals": { "type": "integer", "minimum": 0, "maximum": 18 }, "settlement_reference": { "type": "string", "minLength": 1 } } } }, { "if": { "properties": { "event_kind": { "const": "credit_grant" } }, "required": [ "event_kind" ] }, "then": { "required": [ "credit_amount" ], "properties": { "credit_amount": { "type": "number", "exclusiveMinimum": 0 } } }, "else": { "properties": { "credit_amount": { "type": "number", "maximum": 0 } } } } ], "properties": { "source": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9:_-]+$", "description": "Provider-qualified source. Subscription events use stripe:*, solana:mpp:*, or manual_contract:*.\n" }, "source_id": { "type": "string", "minLength": 1, "maxLength": 512, "description": "Globally stable provider event identity." }, "event_kind": { "$ref": "#/components/schemas/BillingEventKind" }, "plan_id": { "type": [ "string", "null" ], "maxLength": 64 }, "provider_subscription_id": { "type": [ "string", "null" ], "maxLength": 512 }, "period_start": { "type": [ "string", "null" ], "format": "date-time", "description": "RFC3339 with an explicit timezone. Original text is preserved in canonical hashing and final event results.\n" }, "period_end": { "type": [ "string", "null" ], "format": "date-time", "description": "RFC3339 with an explicit timezone and later than period_start.\n" }, "settlement_asset": { "type": [ "string", "null" ], "maxLength": 16, "description": "Normalized to uppercase." }, "settlement_network": { "type": [ "string", "null" ], "maxLength": 128, "description": "Normalized to lowercase before hashing and proof uniqueness checks." }, "settlement_amount_atomic": { "oneOf": [ { "type": "string", "pattern": "^[0-9]{1,38}$" }, { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "settlement_decimals": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 18 }, "settlement_reference": { "type": [ "string", "null" ], "maxLength": 512, "description": "Globally unique together with lowercase settlement_network when present, regardless of source or tenant.\n" }, "credit_amount": { "type": "number", "minimum": 0, "maximum": 1000000000, "multipleOf": 1e-08, "default": 0 }, "provider_metadata": { "type": "object", "additionalProperties": true, "description": "Small public provider references only. Secret, private, credential, token, mandate, authorization, and signature keys are rejected.\n" }, "metadata": { "type": "object", "additionalProperties": true, "description": "Non-sensitive metadata copied to the credit ledger when applicable. The same secret/private/token/mandate/signature key filter applies.\n" } } }, "BillingSubscriptionSnapshot": { "type": "object", "required": [ "plan_id", "status", "billing_provider", "provider_subscription_id", "current_period_start", "current_period_end", "grace_until" ], "properties": { "plan_id": { "type": "string" }, "status": { "type": "string", "enum": [ "free", "incomplete", "active", "past_due", "cancelled", "expired" ] }, "billing_provider": { "type": [ "string", "null" ], "enum": [ "stripe", "solana_mpp", "manual_contract", null ] }, "provider_subscription_id": { "type": [ "string", "null" ] }, "current_period_start": { "type": [ "string", "null" ], "format": "date-time" }, "current_period_end": { "type": [ "string", "null" ], "format": "date-time" }, "grace_until": { "type": [ "string", "null" ], "format": "date-time" } } }, "BillingCreditResult": { "type": "object", "required": [ "granted", "balance_after" ], "properties": { "granted": { "type": "number" }, "balance_after": { "type": "number" } } }, "BillingEventApplyResult": { "type": "object", "required": [ "event_id", "applied", "replay", "subscription" ], "description": "Subscription is null for pure credit_grant events. Ignored events keep applied false and include a stable ignored_reason. An identical source replay sets replay true and applied false while preserving the stored subscription, credit, ignored_reason, and event id.\n", "properties": { "event_id": { "type": "string", "format": "uuid" }, "applied": { "type": "boolean" }, "replay": { "type": "boolean" }, "subscription": { "oneOf": [ { "$ref": "#/components/schemas/BillingSubscriptionSnapshot" }, { "type": "null" } ] }, "ignored_reason": { "type": "string", "enum": [ "stale_period", "subscription_cancelled", "grace_elapsed" ] }, "credit": { "$ref": "#/components/schemas/BillingCreditResult" } } }, "BillingEventRecord": { "type": "object", "required": [ "id", "tenant_id", "source", "source_id", "event_kind", "request_hash", "credit_amount", "result", "created_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "tenant_id": { "type": "string", "format": "uuid" }, "source": { "type": "string" }, "source_id": { "type": "string" }, "event_kind": { "$ref": "#/components/schemas/BillingEventKind" }, "request_hash": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "plan_id": { "type": [ "string", "null" ] }, "provider_subscription_id": { "type": [ "string", "null" ] }, "period_start": { "type": [ "string", "null" ], "format": "date-time" }, "period_end": { "type": [ "string", "null" ], "format": "date-time" }, "settlement_asset": { "type": [ "string", "null" ] }, "settlement_network": { "type": [ "string", "null" ], "description": "Lowercase canonical network identifier." }, "settlement_amount_atomic": { "type": [ "string", "null" ], "pattern": "^[0-9]+$" }, "settlement_decimals": { "type": [ "integer", "null" ] }, "settlement_reference": { "type": [ "string", "null" ] }, "credit_amount": { "type": "string", "description": "PostgreSQL numeric serialized without precision loss." }, "result": { "$ref": "#/components/schemas/BillingEventApplyResult" }, "created_at": { "type": "string", "format": "date-time" } } }, "BillingEventsResponse": { "type": "object", "required": [ "events" ], "properties": { "events": { "type": "array", "items": { "$ref": "#/components/schemas/BillingEventRecord" } } } }, "SubscriptionCreditGrantRequest": { "type": "object", "additionalProperties": false, "required": [ "invoice_id", "subscription_id", "plan_id", "amount" ], "description": "Legacy Stripe invoice credit. It is journaled as credit_grant and never creates, reads, or mutates tenant_subscriptions.\n", "properties": { "invoice_id": { "type": "string", "minLength": 1, "maxLength": 512 }, "subscription_id": { "type": "string", "minLength": 1, "maxLength": 512 }, "plan_id": { "type": "string", "minLength": 1, "maxLength": 64 }, "amount": { "type": "number", "exclusiveMinimum": 0, "maximum": 1000000000, "multipleOf": 1e-08 }, "period_start": { "type": [ "string", "null" ], "format": "date-time" }, "period_end": { "type": [ "string", "null" ], "format": "date-time" } } }, "SubscriptionCreditGrantResponse": { "type": "object", "required": [ "ok", "balance_after", "granted" ], "properties": { "ok": { "type": "boolean", "enum": [ true ] }, "balance_after": { "type": "number", "description": "Zero on an identical legacy invoice replay." }, "granted": { "type": "number", "description": "Zero on an identical legacy invoice replay." }, "idempotent_skip": { "type": "boolean" } } }, "BillingEventErrorResponse": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "description": "Includes idempotency_conflict, settlement_proof_conflict, subscription_provider_conflict, subscription_period_conflict, invalid_subscription_transition, and unsupported_billing_event.\n" }, "message": { "type": "string", "description": "Present for validation errors; omitted for conflicts and higher statuses." } } } } } }