{ "openapi": "3.1.0", "info": { "title": "spectron", "description": "", "license": { "name": "BUSL-1.1", "identifier": "BUSL-1.1" }, "version": "0.2.1" }, "paths": { "/api/v1/health": { "get": { "operationId": "health_check", "responses": { "200": { "description": "" }, "500": { "description": "" } } } }, "/api/v1/{context_id}/actions": { "get": { "description": "List live actions (dated events), newest first by write time. `since`/`until` bound the event time. Paginated: follow `page.nextCursor`. Ordered on write time rather than event time because event time is revisable, and a revision under an event-time ordering would move a row across page boundaries mid-walk.", "operationId": "list_actions", "parameters": [ { "name": "context_id", "in": "path", "description": "Spectron context id", "required": true, "schema": { "type": "string" } }, { "name": "actor", "in": "query", "description": "Filter by acting entity, as `/` (e.g. `person/alice`)", "required": false, "schema": { "type": "string" } }, { "name": "verb", "in": "query", "description": "Filter by action verb", "required": false, "schema": { "type": "string" } }, { "name": "since", "in": "query", "description": "Inclusive lower bound on occurred_at (RFC 3339)", "required": false, "schema": { "type": "string" } }, { "name": "until", "in": "query", "description": "Inclusive upper bound on occurred_at (RFC 3339)", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Max rows to return (default 100, max 500)", "required": false, "schema": { "type": "integer", "format": "int32", "minimum": 0 } }, { "name": "cursor", "in": "query", "description": "Continuation token from the previous page's `page.nextCursor`", "required": false, "schema": { "type": "string" } }, { "name": "count", "in": "query", "description": "Also return `page.totalSize` (costs a full count of the filtered set)", "required": false, "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActionListResponseJson" } } } }, "400": { "description": "Invalid pagination parameter, entity ref, or time bound", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "422": { "description": "Invalid context id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "503": { "description": "Server too busy: the per-pod in-flight request cap was exceeded. Retry per the `Retry-After` header.", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait before retrying." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "api_key": [] } ] } }, "/api/v1/{context_id}/attributes": { "get": { "description": "List live attributes, newest first. Live means not superseded and inside its validity window; superseded values are reachable through the entity history endpoint. Paginated: follow `page.nextCursor`.", "operationId": "list_attributes", "parameters": [ { "name": "context_id", "in": "path", "description": "Spectron context id", "required": true, "schema": { "type": "string" } }, { "name": "entity", "in": "query", "description": "Filter to one entity's attributes, as `/` (e.g. `person/alice`)", "required": false, "schema": { "type": "string" } }, { "name": "key", "in": "query", "description": "Filter by attribute key", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Max rows to return (default 100, max 500)", "required": false, "schema": { "type": "integer", "format": "int32", "minimum": 0 } }, { "name": "cursor", "in": "query", "description": "Continuation token from the previous page's `page.nextCursor`", "required": false, "schema": { "type": "string" } }, { "name": "count", "in": "query", "description": "Also return `page.totalSize` (costs a full count of the filtered set)", "required": false, "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AttributeListResponseJson" } } } }, "400": { "description": "Invalid pagination parameter", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "422": { "description": "Invalid context id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "503": { "description": "Server too busy: the per-pod in-flight request cap was exceeded. Retry per the `Retry-After` header.", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait before retrying." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "api_key": [] } ] } }, "/api/v1/{context_id}/audit": { "get": { "description": "Audit view over the trace graph. Returns recent traces with principal/key/time/kind filters.", "operationId": "list_audit", "parameters": [ { "name": "context_id", "in": "path", "description": "Spectron context id", "required": true, "schema": { "type": "string" } }, { "name": "principal", "in": "query", "description": "Filter by principal (api-key id)", "required": false, "schema": { "type": "string" } }, { "name": "key", "in": "query", "description": "Alias for `principal`", "required": false, "schema": { "type": "string" } }, { "name": "kind", "in": "query", "description": "Trace kind filter: decision|retrieval|response", "required": false, "schema": { "$ref": "#/components/schemas/TraceKind" } }, { "name": "since", "in": "query", "description": "Inclusive lower bound on created_at (RFC 3339)", "required": false, "schema": { "type": "string" } }, { "name": "until", "in": "query", "description": "Inclusive upper bound on created_at (RFC 3339)", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Max rows to return (default 100, max 500)", "required": false, "schema": { "type": "integer", "format": "int32", "minimum": 0 } }, { "name": "cursor", "in": "query", "description": "Continuation token from the previous page's `page.nextCursor`", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuditResponseJson" } } } }, "400": { "description": "Invalid query parameter (e.g. unknown kind)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "422": { "description": "Invalid context id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "503": { "description": "Server too busy: the per-pod in-flight request cap was exceeded. Retry per the `Retry-After` header.", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait before retrying." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "api_key": [] } ] } }, "/api/v1/{context_id}/chat": { "post": { "description": "Phase 7.5 — Spectron-as-agent chat endpoint. Resolves the session, retrieves context via the unified /query router, and calls the configured LLM provider; then, only after a successful synthesis (or a tier-2 cache hit), stores the user message and the assistant response via /facts and emits a response_trace. A failed synthesis writes no turn, fact, or response_trace (a retrieval_trace recording the query may still be written). Set `stream=true` for SSE.", "operationId": "chat", "parameters": [ { "name": "context_id", "in": "path", "description": "Spectron context id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatRequestJson" } } }, "required": true }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatResponseJson" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "422": { "description": "Invalid context id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "503": { "description": "Server too busy: the per-pod in-flight request cap was exceeded. Retry per the `Retry-After` header.", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait before retrying." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "api_key": [] } ] } }, "/api/v1/{context_id}/consolidate": { "post": { "description": "Phase 11b: pool recent facts and consolidate into observations. Scope-gated: only facts in the caller's `memory:read` region are pooled, and only groups in the caller's `memory:write` region are persisted (others are returned as dry-run previews).", "operationId": "consolidate", "parameters": [ { "name": "context_id", "in": "path", "description": "Spectron context id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConsolidateRequestJson" } } }, "required": true }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConsolidateResponseJson" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "422": { "description": "Invalid context id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "503": { "description": "Server too busy: the per-pod in-flight request cap was exceeded. Retry per the `Retry-After` header.", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait before retrying." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "api_key": [] } ] } }, "/api/v1/{context_id}/context": { "post": { "description": "Query memory and return formatted context for LLM prompt injection", "operationId": "query_context", "parameters": [ { "name": "context_id", "in": "path", "description": "Spectron context id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContextQueryRequestJson" } } }, "required": true }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContextQueryResponseJson" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "422": { "description": "Invalid context id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "503": { "description": "Server too busy: the per-pod in-flight request cap was exceeded. Retry per the `Retry-After` header.", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait before retrying." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "api_key": [] } ] } }, "/api/v1/{context_id}/documents": { "get": { "description": "Lists Layer 0 knowledge documents", "operationId": "list_documents", "parameters": [ { "name": "context_id", "in": "path", "description": "Spectron context id", "required": true, "schema": { "type": "string" } }, { "name": "status", "in": "query", "description": "Filter by document status", "required": false, "schema": { "type": "string" } }, { "name": "mimeType", "in": "query", "description": "Filter by mime type", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Max documents to return (default 100, max 500)", "required": false, "schema": { "type": "integer", "format": "int32", "minimum": 0 } }, { "name": "cursor", "in": "query", "description": "Continuation token from the previous page's `page.nextCursor`", "required": false, "schema": { "type": "string" } }, { "name": "count", "in": "query", "description": "Also return `page.totalSize` (costs a full count of the filtered set)", "required": false, "schema": { "type": "boolean" } }, { "name": "page", "in": "query", "description": "Deprecated: zero-based page index. Use `cursor`.", "required": false, "schema": { "type": "integer", "format": "int32", "minimum": 0 } }, { "name": "pageSize", "in": "query", "description": "Deprecated: page size. Use `limit`.", "required": false, "schema": { "type": "integer", "format": "int32", "minimum": 0 } } ], "responses": { "200": { "description": "Documents", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentPageJson" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "422": { "description": "Invalid context id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "500": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "503": { "description": "Server too busy: the per-pod in-flight request cap was exceeded. Retry per the `Retry-After` header.", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait before retrying." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "api_key": [] } ] }, "post": { "description": "Upload a new Layer 0 knowledge document (multipart/form-data)", "operationId": "upload_document", "parameters": [ { "name": "context_id", "in": "path", "description": "Spectron context id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/DocumentUploadForm" } } }, "required": true }, "responses": { "202": { "description": "Upload accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UploadResponse" } } } }, "400": { "description": "Malformed multipart, scope, or label", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "403": { "description": "Requested scope outside the caller's write region", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "409": { "description": "Label count exceeds the per-fact cap", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "415": { "description": "Unsupported media type", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "422": { "description": "Invalid context id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "500": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "503": { "description": "Server too busy: the per-pod in-flight request cap was exceeded. Retry per the `Retry-After` header.", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait before retrying." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "api_key": [] } ] } }, "/api/v1/{context_id}/documents/keywords": { "get": { "description": "Lists keywords across the Context", "operationId": "list_keywords", "parameters": [ { "name": "context_id", "in": "path", "description": "Spectron context id", "required": true, "schema": { "type": "string" } }, { "name": "q", "in": "query", "description": "Case-insensitive substring match on text", "required": false, "schema": { "type": "string" } }, { "name": "minDocumentCount", "in": "query", "description": "Minimum number of linked documents", "required": false, "schema": { "type": "integer", "format": "int64" } }, { "name": "sort", "in": "query", "description": "Sort key", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Max keywords to return (default 100, max 500)", "required": false, "schema": { "type": "integer", "format": "int32", "minimum": 0 } }, { "name": "cursor", "in": "query", "description": "Continuation token from the previous page's `page.nextCursor`. Only valid for the `sort` it was minted under.", "required": false, "schema": { "type": "string" } }, { "name": "count", "in": "query", "description": "Also return `page.totalSize` (costs a full count of the filtered set)", "required": false, "schema": { "type": "boolean" } }, { "name": "page", "in": "query", "description": "Deprecated: zero-based page index. Use `cursor`.", "required": false, "schema": { "type": "integer", "format": "int32", "minimum": 0 } }, { "name": "pageSize", "in": "query", "description": "Deprecated: page size. Use `limit`.", "required": false, "schema": { "type": "integer", "format": "int32", "minimum": 0 } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KeywordPageJson" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "422": { "description": "Invalid context id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "503": { "description": "Server too busy: the per-pod in-flight request cap was exceeded. Retry per the `Retry-After` header.", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait before retrying." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "api_key": [] } ] } }, "/api/v1/{context_id}/documents/keywords/search": { "post": { "description": "HNSW vector search over keyword embeddings", "operationId": "search_keywords", "parameters": [ { "name": "context_id", "in": "path", "description": "Spectron context id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KeywordSearchRequestJson" } } }, "required": true }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KeywordSearchResponseJson" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "422": { "description": "Invalid context id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "503": { "description": "Server too busy: the per-pod in-flight request cap was exceeded. Retry per the `Retry-After` header.", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait before retrying." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "api_key": [] } ] } }, "/api/v1/{context_id}/documents/keywords/{normalised}": { "get": { "description": "Gets a keyword and its linked documents", "operationId": "get_keyword", "parameters": [ { "name": "context_id", "in": "path", "description": "Spectron context id", "required": true, "schema": { "type": "string" } }, { "name": "normalised", "in": "path", "description": "Uppercase canonical keyword form", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KeywordDetailJson" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "404": { "description": "Keyword not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "422": { "description": "Invalid context id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "503": { "description": "Server too busy: the per-pod in-flight request cap was exceeded. Retry per the `Retry-After` header.", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait before retrying." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "api_key": [] } ] } }, "/api/v1/{context_id}/documents/query": { "post": { "description": "Runs a top-k semantic query over the Layer 0 chunks", "operationId": "query_documents", "parameters": [ { "name": "context_id", "in": "path", "description": "Spectron context id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueryRequestJson" } } }, "required": true }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueryResponseJson" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "422": { "description": "Invalid context id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "500": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "503": { "description": "Server too busy: the per-pod in-flight request cap was exceeded. Retry per the `Retry-After` header.", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait before retrying." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "api_key": [] } ] } }, "/api/v1/{context_id}/documents/recompute-links": { "post": { "description": "Phase 6c: recompute doc-to-doc semantic_similarity edges across the Context. Returns the number of edges emitted (existing edges are retained — the (in, out, kind) triple is unique).", "operationId": "recompute_document_links", "parameters": [ { "name": "context_id", "in": "path", "description": "Spectron context id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecomputeLinksResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "422": { "description": "Invalid context id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "500": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "503": { "description": "Server too busy: the per-pod in-flight request cap was exceeded. Retry per the `Retry-After` header.", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait before retrying." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "api_key": [] } ] } }, "/api/v1/{context_id}/documents/{id}": { "get": { "description": "Gets a Layer 0 knowledge document by id", "operationId": "get_document", "parameters": [ { "name": "context_id", "in": "path", "description": "Spectron context id", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "description": "Document id fragment", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Document", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentJson" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "404": { "description": "Document not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "422": { "description": "Invalid context id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "500": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "503": { "description": "Server too busy: the per-pod in-flight request cap was exceeded. Retry per the `Retry-After` header.", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait before retrying." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "api_key": [] } ] }, "put": { "description": "Replaces a Layer 0 knowledge document and re-runs its pipeline", "operationId": "reprocess_document", "parameters": [ { "name": "context_id", "in": "path", "description": "Spectron context id", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "description": "Document id fragment", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/DocumentUploadForm" } } }, "required": true }, "responses": { "202": { "description": "Upload accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UploadResponse" } } } }, "400": { "description": "Malformed multipart", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "404": { "description": "Document not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "415": { "description": "Unsupported media type", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "422": { "description": "Invalid context id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "500": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "503": { "description": "Server too busy: the per-pod in-flight request cap was exceeded. Retry per the `Retry-After` header.", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait before retrying." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "api_key": [] } ] }, "delete": { "description": "Deletes a Layer 0 knowledge document", "operationId": "delete_document", "parameters": [ { "name": "context_id", "in": "path", "description": "Spectron context id", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "description": "Document id fragment", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Document deleted" }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "404": { "description": "Document not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "422": { "description": "Invalid context id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "500": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "503": { "description": "Server too busy: the per-pod in-flight request cap was exceeded. Retry per the `Retry-After` header.", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait before retrying." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "api_key": [] } ] } }, "/api/v1/{context_id}/documents/{id}/chunks": { "get": { "description": "Lists chunks for a document", "operationId": "list_chunks", "parameters": [ { "name": "context_id", "in": "path", "description": "Spectron context id", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "description": "Document id fragment", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Max chunks to return (default 100, max 500)", "required": false, "schema": { "type": "integer", "format": "int32", "minimum": 0 } }, { "name": "cursor", "in": "query", "description": "Continuation token from the previous page's `page.nextCursor`", "required": false, "schema": { "type": "string" } }, { "name": "count", "in": "query", "description": "Also return `page.totalSize` (costs a full count of the document's chunks)", "required": false, "schema": { "type": "boolean" } }, { "name": "page", "in": "query", "description": "Deprecated: zero-based page index. Use `cursor`.", "required": false, "schema": { "type": "integer", "format": "int32", "minimum": 0 } }, { "name": "pageSize", "in": "query", "description": "Deprecated: page size. Use `limit`.", "required": false, "schema": { "type": "integer", "format": "int32", "minimum": 0 } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChunkPageJson" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "404": { "description": "Document not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "422": { "description": "Invalid context id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "500": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "503": { "description": "Server too busy: the per-pod in-flight request cap was exceeded. Retry per the `Retry-After` header.", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait before retrying." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "api_key": [] } ] } }, "/api/v1/{context_id}/documents/{id}/keywords": { "get": { "description": "Lists keywords linked to a single document", "operationId": "list_document_keywords", "parameters": [ { "name": "context_id", "in": "path", "description": "Spectron context id", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "description": "Document id fragment", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentKeywordsResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "404": { "description": "Document not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "422": { "description": "Invalid context id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "503": { "description": "Server too busy: the per-pod in-flight request cap was exceeded. Retry per the `Retry-After` header.", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait before retrying." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "api_key": [] } ] } }, "/api/v1/{context_id}/documents/{id}/raw": { "get": { "description": "Streams the raw bytes of a document", "operationId": "fetch_document_raw", "parameters": [ { "name": "context_id", "in": "path", "description": "Spectron context id", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "description": "Document id fragment", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Raw bytes" }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "404": { "description": "Document not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "422": { "description": "Invalid context id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "500": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "503": { "description": "Server too busy: the per-pod in-flight request cap was exceeded. Retry per the `Retry-After` header.", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait before retrying." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "api_key": [] } ] } }, "/api/v1/{context_id}/elaborate": { "post": { "description": "Phase 11a: elaborate links for a single entity or sweep low-relation entities", "operationId": "elaborate", "parameters": [ { "name": "context_id", "in": "path", "description": "Spectron context id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ElaborateRequestJson" } } }, "required": true }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ElaborateResponseJson" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "422": { "description": "Invalid context id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "503": { "description": "Server too busy: the per-pod in-flight request cap was exceeded. Retry per the `Retry-After` header.", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait before retrying." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "api_key": [] } ] } }, "/api/v1/{context_id}/entities": { "get": { "description": "List entities (optionally filtered by type), ordered by type then name. Paginated: `limit` defaults to 100 and is capped at 500; follow `page.nextCursor` to walk the Context.", "operationId": "list_entities", "parameters": [ { "name": "context_id", "in": "path", "description": "Spectron context id", "required": true, "schema": { "type": "string" } }, { "name": "type", "in": "query", "description": "Filter by entity type", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Max entities to return (default 100, max 500)", "required": false, "schema": { "type": "integer", "format": "int32", "minimum": 0 } }, { "name": "cursor", "in": "query", "description": "Continuation token from the previous page's `page.nextCursor`", "required": false, "schema": { "type": "string" } }, { "name": "count", "in": "query", "description": "Also return `page.totalSize` (costs a full count of the filtered set)", "required": false, "schema": { "type": "boolean" } }, { "name": "offset", "in": "query", "description": "Deprecated: rows to skip. Use `cursor`.", "required": false, "schema": { "type": "integer", "format": "int32", "minimum": 0 } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntityListResponseJson" } } } }, "400": { "description": "Invalid pagination parameter", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "422": { "description": "Invalid context id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "503": { "description": "Server too busy: the per-pod in-flight request cap was exceeded. Retry per the `Retry-After` header.", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait before retrying." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "api_key": [] } ] } }, "/api/v1/{context_id}/entities/{entity_type}/{entity_name}": { "get": { "description": "Get a single entity with its current attributes and relations", "operationId": "get_entity", "parameters": [ { "name": "context_id", "in": "path", "description": "Spectron context id", "required": true, "schema": { "type": "string" } }, { "name": "entity_type", "in": "path", "description": "Entity type", "required": true, "schema": { "type": "string" } }, { "name": "entity_name", "in": "path", "description": "Entity name", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntityResponseJson" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "404": { "description": "Entity not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "422": { "description": "Invalid context id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "503": { "description": "Server too busy: the per-pod in-flight request cap was exceeded. Retry per the `Retry-After` header.", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait before retrying." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "api_key": [] } ] }, "delete": { "description": "Soft-delete an entity and all its current attributes and relations", "operationId": "delete_entity", "parameters": [ { "name": "context_id", "in": "path", "description": "Spectron context id", "required": true, "schema": { "type": "string" } }, { "name": "entity_type", "in": "path", "description": "Entity type", "required": true, "schema": { "type": "string" } }, { "name": "entity_name", "in": "path", "description": "Entity name", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Entity soft-deleted" }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "422": { "description": "Invalid context id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "503": { "description": "Server too busy: the per-pod in-flight request cap was exceeded. Retry per the `Retry-After` header.", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait before retrying." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "api_key": [] } ] } }, "/api/v1/{context_id}/entities/{entity_type}/{entity_name}/history/{key}": { "get": { "description": "Get the full attribute history (supersession chain) for an entity key", "operationId": "get_entity_history", "parameters": [ { "name": "context_id", "in": "path", "description": "Spectron context id", "required": true, "schema": { "type": "string" } }, { "name": "entity_type", "in": "path", "description": "Entity type", "required": true, "schema": { "type": "string" } }, { "name": "entity_name", "in": "path", "description": "Entity name", "required": true, "schema": { "type": "string" } }, { "name": "key", "in": "path", "description": "Attribute key", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntityHistoryResponseJson" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "404": { "description": "Entity not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "422": { "description": "Invalid context id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "503": { "description": "Server too busy: the per-pod in-flight request cap was exceeded. Retry per the `Retry-After` header.", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait before retrying." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "api_key": [] } ] } }, "/api/v1/{context_id}/facts": { "post": { "description": "Write a single fact. Dispatches on `infer` mode: full (LLM-extracted), triples (caller-supplied), preview (dry run), none (literal).", "operationId": "create_fact", "parameters": [ { "name": "context_id", "in": "path", "description": "Spectron context id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FactsRequest" } } }, "required": true }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FactsResponseJson" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "409": { "description": "Idempotency-Key reused with a different body", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "422": { "description": "Invalid context id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "503": { "description": "Server too busy: the per-pod in-flight request cap was exceeded. Retry per the `Retry-After` header.", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait before retrying." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "api_key": [] } ] } }, "/api/v1/{context_id}/facts/batch": { "post": { "description": "Bulk conversation ingest. Persists each message as a turn and routes extraction through `reconcile_extraction`.", "operationId": "create_facts_batch", "parameters": [ { "name": "context_id", "in": "path", "description": "Spectron context id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FactsBatchRequest" } } }, "required": true }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FactsBatchResponseJson" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "409": { "description": "Idempotency-Key reused with a different body", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "422": { "description": "Invalid context id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "503": { "description": "Server too busy: the per-pod in-flight request cap was exceeded. Retry per the `Retry-After` header.", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait before retrying." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "api_key": [] } ] } }, "/api/v1/{context_id}/forget": { "post": { "description": "Semantic forget: finds matching memories by similarity and soft-deletes them", "operationId": "forget", "parameters": [ { "name": "context_id", "in": "path", "description": "Spectron context id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForgetRequestJson" } } }, "required": true }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForgetResponseJson" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "422": { "description": "Invalid context id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "503": { "description": "Server too busy: the per-pod in-flight request cap was exceeded. Retry per the `Retry-After` header.", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait before retrying." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "api_key": [] } ] } }, "/api/v1/{context_id}/fsck": { "post": { "description": "Memory hygiene sweep (duplicates / contradictions / injection / unscoped content)", "operationId": "fsck", "parameters": [ { "name": "context_id", "in": "path", "description": "Spectron context id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FsckRequestJson" } } }, "required": true }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FsckReportJson" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "422": { "description": "Invalid context id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "503": { "description": "Server too busy: the per-pod in-flight request cap was exceeded. Retry per the `Retry-After` header.", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait before retrying." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } }, "security": [ { "api_key": [] } ] } }, "/api/v1/{context_id}/inspect": { "get": { "description": "Resolve an inspect ref (entity, attribute, relation, passage, or trace) to a normalised view. Ref grammar: `entity:/`, `attribute://`, `relation:/-[