dify/knowledge-fs/docs/api-reference.md

Knowledge-FS Gateway — API Reference

Human-readable reference for the HTTP API served by the gateway (apps/api, Hono + zod-openapi). It is maintained alongside the route definitions in packages/api/src/*-routes.ts and their zod request/response schemas. GET /openapi.json is the authoritative machine-readable inventory when the live spec and this companion document differ.

Overview

• Base URL (local dev): http://localhost:8788 (the gateway). The Swagger UI proxy runs on http://localhost:8088 and fetches /openapi.json from the gateway.
• Live spec: GET /openapi.json — the machine-readable OpenAPI document (public, unauthenticated), served via app.doc(...). This reference is a human-readable companion.
• Content type: JSON (application/json) unless noted; document upload is multipart/form-data; streaming answers/progress are text/event-stream; raw multimodal assets are application/octet-stream.

Authentication & scopes

• Bearer token (JWT) on every guarded route: Authorization: Bearer <token>. The tenant is taken from the JWT; a knowledge space is always resolved as spaces.get({ id, tenantId }), so one tenant can never read another tenant's space (returns 404).
• Scopes (getRequiredScope): every GET needs knowledge-spaces:read; every POST/PATCH/DELETE needs knowledge-spaces:write — except POST /queries, POST /research-tasks/plan, and POST /agent-workspace-snapshots/{id}/replay, which need only read. The wildcard scope knowledge-spaces:* satisfies both.
• Auth is path-prefix middleware, not per-route: it guards /knowledge-spaces*, /queries*, /jobs*, /research-tasks*, /agent-workspace-snapshots*, /bulk-jobs*, /retention-policy. Public (no auth): GET /health and GET /openapi.json.
• Auth failures: 401 (missing/invalid token), 403 (token lacks the required scope), both { error: string }.

Conventions

• Errors: non-2xx bodies are { error: string } (unless a richer shape is documented, e.g. research task 422).
• Pagination: list endpoints take cursor (opaque string) + limit, and return { items: [...], nextCursor?: string }. Pass nextCursor back as cursor for the next page.
• Strict bodies/queries: most request bodies and query objects are .strict() — unknown keys are rejected with 400.
• SSE: streaming endpoints return text/event-stream; frames are event: <name>\ndata: <json>\n\n.
• Datetimes are ISO-8601 strings unless a field is documented as an epoch number.

---

Knowledge spaces & documents

POST /knowledge-spaces

Description: Create a new knowledge space for the caller's tenant. Auth: Bearer; scope knowledge-spaces:write. Path params: None. Query params: None. Request body (application/json, strict): name (string, 1–160, required); slug (string, required, ^[a-z0-9]+(?:-[a-z0-9]+)*$) — tenant-unique; description (string, ≤2000, optional); embeddingProfile (optional) { pluginId, provider, model }. When omitted, the configured deployment default is persisted for new spaces. Clients cannot set credentials, dimension, revision, or vectorSpaceId. Responses:

• 201: KnowledgeSpace { id: uuid, name, slug, description?, tenantId, createdAt, updatedAt }.
• 409 slug conflict; 429 capacity exceeded; 401/403.

GET /knowledge-spaces

Description: List the tenant's knowledge spaces (cursor-paginated). Auth: Bearer; scope knowledge-spaces:read. Query params (strict): limit (int ≥1, optional, default 100); cursor (string, optional). Responses: 200 { items: KnowledgeSpace[], nextCursor?: string }; 400; 401/403.

GET /knowledge-spaces/{id}

Description: Fetch a single knowledge space by id. Auth: Bearer; scope knowledge-spaces:read. Path params: id (uuid). Responses: 200 KnowledgeSpace; 404; 401/403.

GET /knowledge-spaces/{id}/manifest

Description: Return the space's control-plane manifest (storage/consistency/quota policies). Auth: Bearer; scope knowledge-spaces:read. Path params: id (uuid). Responses:

• 200: KnowledgeSpaceManifest — { id, knowledgeSpaceId, tenantId, manifestVersion: int, embeddingProfile?: { pluginId, provider, model, vectorSpaceId, revision, dimension? }, embeddingProfileFrozenAt?: datetime, minClientVersion, nodeSchemaVersion: int, parserPolicyVersion, projectionSetVersion, objectKeyPrefix, metadataDialect: enum(portable|postgres|tidb), storageProvider: enum(memory-dev|r2|s3-compatible), consistencyPolicy: { defaultClass: enum(path-consistent|snapshot-consistent|cache-consistent|eventual-preview), snapshotTtlSeconds, cacheTtlSeconds? }, encryptionPolicy: { strategy: enum(provider-managed|customer-managed|none), keyRef? }, retentionPolicy: { artifactVersionsToKeep, failedCommitRetentionDays, traceRetentionDays }, quotaPolicy: { maxActiveJobCount, maxActiveSessionCount, maxArtifactBytes, maxGraphEntityCount, maxGraphRelationCount, maxNodeCount, maxProjectionCount, maxRawDocumentBytes, maxSegmentCount, maxTraceBytes: int|null, providerBudgets: { maxEmbeddingTokensPerDay, maxLlmTokensPerDay, maxParserPagesPerDay, maxRerankRequestsPerDay: int|null } }, metadata, createdAt, updatedAt }. embeddingProfileFrozenAt is set atomically when the first document ingestion is admitted.
• 404; 401/403.

PUT /knowledge-spaces/{id}/embedding-profile

Description: Bind the space to a plugin-daemon embedding route and immutable vector-space identity. Auth: Bearer; scope knowledge-spaces:write. Path params: id (uuid). Request body (application/json, strict): { pluginId, provider, model } (all non-empty strings). Credentials remain tenant-scoped in plugin-daemon. The server owns vectorSpaceId, revision, and the dimension observed from the first real model response. Responses:

• 200: { pluginId, provider, model, vectorSpaceId, revision, dimension? }.
• 409: ingestion has already been admitted (or legacy content exists), so the candidate reindex/publish workflow is required before changing vector space. The admission latch is fail-closed and remains set even if the first upload later fails.
• 404; 401/403.

GET /knowledge-spaces/{id}/status

Description: Bounded runtime status snapshot (leases, sessions, failed commits, index health, storage/parser). Auth: Bearer; scope knowledge-spaces:read. Path params: id (uuid). Responses:

• 200: KnowledgeSpaceStatus { knowledgeSpaceId, tenantId, generatedAt, activeLeases: { count, truncated, items: [{ id, leaseType: enum(read|publish|delete|reindex), targetType, virtualPath, expiresAt }] }, activeSessions: { count, truncated, items: [{ id, subjectId, clientKind: enum(api|mcp|worker|admin), consistencyClass, heartbeatAt, expiresAt }] }, failedCommits: { count, truncated, items: [{ id, status: enum(failed-retryable|failed-terminal), errorCode?, expiresAt?, updatedAt }] }, index: { nodeSchemaVersion, projectionVersion, projectionSetVersion, summaries: { denseVector, fts, graph, metadata: { total, ready, building, stale, failed } } }, manifest: { manifestVersion, metadataDialect, storageProvider, objectKeyPrefix, consistencyClass }, parser: { kind, policyVersion }, storage: { healthy, provider, objectStorageKind } }.
• 404; 401/403.

GET /knowledge-spaces/{id}/stats

Description: Low-cardinality aggregate statistics over a time window. Auth: Bearer; scope knowledge-spaces:read. Path params: id (uuid). Query (strict): windowMinutes (int 1–1440, optional, default 60). Responses:

• 200: KnowledgeSpaceStats { knowledgeSpaceId, tenantId, generatedAt, window: { start, end, minutes }, storage: { documentCount, rawDocumentBytes }, projections: { denseVector, fts, graph, metadata: { total, ready, building, stale, failed }, projectionVersion }, commits: { failedRetryable, failedTerminal, sampled, truncated }, cache: { available, entries, totalBytes }, metrics: { available, reason? }, runtime: { activeLeaseSampleCount, activeSessionSampleCount, truncated } }.
• 400; 404; 401/403.

GET /knowledge-spaces/{id}/fsck

Description: Bounded filesystem-consistency diagnostics over one check class. Auth: Bearer; scope knowledge-spaces:read. Path params: id (uuid). Query (strict): check (enum raw-objects|artifact-segments|references, optional, default raw-objects); cursor (string 1–1024, optional). Responses:

• 200: KnowledgeFsckReport { knowledgeSpaceId, tenantId, scannedAt, cursor?, summary: { scanned, info, warning, error, critical, repairable }, issues: [{ code, message, type: enum(missing-raw-object|checksum-mismatch|size-mismatch|missing-artifact-object|segment-hash-mismatch|broken-path-target|missing-node-target|stale-projection|orphaned-staged-object|failed-commit-expired), severity: enum(info|warning|error|critical), repairability: enum(auto-repairable|manual|not-repairable), target: { type, id?, objectKey?, documentAssetId?, parseArtifactId?, virtualPath? } }] (≤1000) }.
• 400; 404; 401/403.

GET /knowledge-spaces/{id}/gc/staged-objects

Description: Bounded dry-run listing of staged-object / failed-commit GC candidates. Auth: Bearer; scope knowledge-spaces:read. Path params: id (uuid). Query (strict): cursor (string 1–1024, optional); stagedObjectPrefix (string 1–1024, object-key-prefix regex, optional). Responses:

• 200: KnowledgeFsGcDryRunReport { knowledgeSpaceId, tenantId, dryRunId, generatedAt, cursor?, summary: { candidateCount, stagedObjectCount, failedCommitCount, estimatedBytes }, candidates: [{ candidateType: enum(staged-object|failed-commit|artifact-segment|parse-artifact|index-projection|answer-trace), count>0, estimatedBytes, idempotencyKey, reason, target: {...} }] (≤1000) }.
• 400; 404; 401/403.

POST /knowledge-spaces/{id}/gc/staged-objects/execute

Description: Execute deletion for supplied GC candidates (skips objects with an active lease). Auth: Bearer; scope knowledge-spaces:write. Path params: id (uuid). Request body (application/json, strict): candidates (array ≤100, required) — each { candidateType, count>0, estimatedBytes≥0, idempotencyKey (1–512), reason (1–1000), target: { type: enum(raw-object|artifact-object|artifact-segment|knowledge-path|knowledge-node|index-projection|staged-commit), id?, objectKey?, documentAssetId?, parseArtifactId?, virtualPath? } }. Responses:

• 200: { tenantId, deleted: int, skipped: int, items: [{ objectKey, idempotencyKey, status: enum(deleted|skipped-active-lease) }] }.
• 400; 404; 401/403.

GET /knowledge-spaces/{id}/staged-commits

Description: Read-only paginated staged-commit diagnostics, optionally filtered by status. Auth: Bearer; scope knowledge-spaces:read. Path params: id (uuid). Query (strict): limit (int ≥1, optional, default 100); cursor (uuid, optional); status (enum received|object-staged|object-verified|metadata-prepared|artifacts-built|nodes-built|projections-built|published|failed-retryable|failed-terminal|canceled|gc-pending|gc-complete, optional). Responses:

• 200: { items: KnowledgeSpaceStagedCommit[], nextCursor? } — each { id, knowledgeSpaceId, tenantId, idempotencyKey, operationType: enum(document-upload|artifact-segment-write|bulk-reindex|projection-publish), status, documentAssetId?, parseArtifactId?, rawObjectKey?, publishedObjectKey?, projectionFingerprint?, checksum?, sizeBytes?, errorCode?, errorMessage?, expiresAt?, createdAt, updatedAt }.
• 400; 404; 401/403.

GET /knowledge-spaces/{id}/leases/active

Description: Read-only paginated diagnostics of currently active KnowledgeFS leases. Auth: Bearer; scope knowledge-spaces:read. Path params: id (uuid). Query (strict): limit (int ≥1, optional, default 100); cursor (string 1–1024, optional). Responses:

• 200: { items: KnowledgeFsLease[], nextCursor? } — each { id, knowledgeSpaceId, tenantId, sessionId, leaseType: enum(read|publish|delete|reindex), status: enum(active|released|expired|failed), targetId, targetType, targetVersion?, virtualPath, metadata, acquiredAt, heartbeatAt, expiresAt, updatedAt }.
• 400; 404; 401/403.

PATCH /knowledge-spaces/{id}

Description: Update mutable fields (name/slug/description). Auth: Bearer; scope knowledge-spaces:write. Path params: id (uuid). Body (application/json, strict, all optional): name (1–160); slug (slug regex); description (≤2000). Responses: 200 KnowledgeSpace; 404; 409 slug conflict; 401/403.

DELETE /knowledge-spaces/{id}

Description: Delete a knowledge space. Auth: Bearer; scope knowledge-spaces:write. Path params: id (uuid). Responses: 204; 404; 401/403.

GET /knowledge-spaces/{id}/documents

Description: List document assets (cursor-paginated). Auth: Bearer; scope knowledge-spaces:read. Path params: id (uuid). Query (strict): limit (int 1–100, optional, default 50); cursor (uuid, optional). Responses:

• 200: { items: DocumentAsset[], nextCursor?: uuid } — each DocumentAsset { id, knowledgeSpaceId, sourceId?, filename, mimeType, objectKey, sha256, sizeBytes, parserStatus: enum(pending|parsed|failed), version: int>0, metadata, createdAt, updatedAt? }.
• 404; 401/403.

GET /knowledge-spaces/{id}/documents/{documentId}

Description: Fetch a single document asset. Auth: Bearer; scope knowledge-spaces:read. Path params: id (uuid); documentId (uuid). Responses: 200 DocumentAsset; 404; 401/403.

GET /knowledge-spaces/{id}/documents/{documentId}/parse-artifacts/{version}

Description: Fetch a specific version of a document's parse artifact (parsed elements). Auth: Bearer; scope knowledge-spaces:read. Path params: id (uuid); documentId (uuid); version (positive int). Responses:

• 200: ParseArtifact { id, documentAssetId, artifactHash, contentType: enum(text|structured|mixed), parser: enum(native-markdown|native-html|native-structured|unstructured), version: int>0, elements: [{ id, type: enum(title|heading|paragraph|table|list|image|code|page-break), text?, pageNumber?, sectionPath: string[], metadata }], metadata, createdAt, updatedAt? }.
• 404; 401/403.

GET /knowledge-spaces/{id}/documents/{documentId}/outline

Description: Fetch a document's hierarchical outline / table of contents. Auth: Bearer; scope knowledge-spaces:read. Path params: id (uuid); documentId (uuid). Responses:

• 200: DocumentOutline { id, knowledgeSpaceId, documentAssetId, parseArtifactId, artifactHash, outlineVersion, version: int>0, nodes: DocumentOutlineNode[], metadata, createdAt, updatedAt? }; each node { id, title, level: int>0, tocSource, sectionPath: string[], childNodeIds: string[], children: node[] (recursive), sourceElementIds: string[], sourceNodeIds: string[], startOffset?, endOffset?, startPage?, endPage?, summary?, titleLocation?, metadata }.
• 404; 401/403.

GET /knowledge-spaces/{id}/documents/{documentId}/multimodal

Description: Fetch a document's multimodal manifest (images/tables/pages/code + enrichment status). Auth: Bearer; scope knowledge-spaces:read. Path params: id (uuid); documentId (uuid). Responses:

• 200: DocumentMultimodalManifest { id, knowledgeSpaceId, documentAssetId, parseArtifactId, artifactHash, manifestVersion, version: int>0, items: [{ id, parseElementId, modality: enum(code|image|page|table), title?, caption?, textPreview?, ocrText?, pageNumber?, boundingBox?: { x, y, width, height }, sectionPath: string[], startOffset?, endOffset?, assetRef?: { objectKey?, uri?, contentType?, sha256?, variants?: Record<string,{ objectKey?, uri?, contentType?, sha256?, width?, height? }> }, enrichment: { asset, caption, ocr, tableStructure, visualEmbedding: enum(missing|pending|provided|unsupported) }, sourceMetadata } ], metadata, createdAt, updatedAt? }.
• 404; 401/403.

GET /knowledge-spaces/{id}/documents/{documentId}/multimodal/{itemId}/asset

Description: Stream the raw binary asset (or a named variant) for a multimodal item. Auth: Bearer; scope knowledge-spaces:read. Path params: id (uuid); documentId (uuid); itemId (string 1–1024). Query (strict): variant (string 1–64, ^[A-Za-z0-9._=-]+$, optional). Responses:

• 200 (application/octet-stream): binary asset bytes.
• 404 not found; 409 external (non-inline) asset; 413 exceeds max readable size; 401/403.

POST /knowledge-spaces/{id}/documents

Description: Upload a single document — compiled synchronously, or accepted for durable async compilation. Auth: Bearer; scope knowledge-spaces:write. Path params: id (uuid). Request body (multipart/form-data): file (binary, required); sourceId (uuid, optional). Responses:

• 201: DocumentAsset (compiled synchronously).
• 202: { asset: DocumentAsset, compilationJob: { id, stage: "queued" }, statusUrl } (async handoff).
• 400; 404; 413 too large; 429 capacity; 500 upload failed; 401/403.

POST /knowledge-spaces/{id}/documents/bulk

Description: Upload multiple documents for durable async compilation. Auth: Bearer; scope knowledge-spaces:write. Path params: id (uuid). Body (multipart/form-data): files (binary[], required). Responses:

• 202: { bulkJobId, total, items: [{ asset: DocumentAsset, compilationJob: { id, stage: "queued" }, statusUrl }] }.
• 400; 404; 413; 429; 500; 503 durable compilation not configured; 401/403.

DELETE /knowledge-spaces/{id}/documents/bulk

Description: Delete multiple documents by id; report per-document results. Auth: Bearer; scope knowledge-spaces:write. Path params: id (uuid). Body (application/json, strict): documentIds (uuid[], min 1). Responses:

• 200: { bulkJobId, total, items: [{ documentId, status: enum(deleted|not_found), objectDeleted, artifactsDeleted, nodesDeleted, projectionsDeleted }] }.
• 400; 404; 401/403.

POST /knowledge-spaces/{id}/documents/bulk/reindex

Description: Queue reindex (recompilation) of all documents or a specified set. Auth: Bearer; scope knowledge-spaces:write. Path params: id (uuid). Body (application/json, strict; exactly one of): all (boolean) | documentIds (uuid[], min 1). Responses:

• 202: { bulkJobId, total, items: Array<{ asset, compilationJob: { id, stage: "queued" }, status: "queued", statusUrl } | { documentId, status: "not_found" }> }.
• 400; 404; 413 quota; 503 durable compilation not configured; 401/403.

GET /jobs/{id}

Description: Fetch the status of a durable document compilation job. Auth: Bearer; scope knowledge-spaces:read. Path params: id (string, min 1). Responses:

• 200: DocumentCompilationJob { id, knowledgeSpaceId, tenantId, documentAssetId, queueJobId, stage: enum(queued|parsed|outline_built|nodes_generated|projection_built|smoke_eval_passed|published|failed|canceled), version: int>0, error?, createdAt: number, updatedAt: number, completedAt?: number }.
• 404; 503 compilation jobs unavailable; 401/403.

DELETE /jobs/{id}

Description: Cancel a durable document compilation job. Auth: Bearer; scope knowledge-spaces:write. Path params: id (string, min 1). Responses: 200 DocumentCompilationJob (canceled); 404; 409 terminal (cannot cancel); 503; 401/403.

---

Query, answers, golden & failed queries

POST /queries

Description: Run a knowledge-space query and stream the generated answer as SSE. Auth: Bearer; scope knowledge-spaces:read. Request body (application/json, strict): knowledgeSpaceId (uuid, required); query (string 1–16000, required); mode (enum auto|deep|fast|research, optional; defaults to the published knowledge-space retrieval profile's defaultMode, or fast for a legacy space without a profile); activeDocumentIds (uuid[] ≤100, optional, default []); activeEntityIds (string[1–200][] ≤100, optional, default []); sessionId (uuid, optional).

auto is a public routing selector, not a fourth retrieval pipeline. Only an explicit mode: "auto" invokes the knowledge space's published reasoningModel through plugin-daemon to select exactly one concrete pipeline. Omitting mode does not invoke the router; it uses the published defaultMode. Explicit fast, research, and deep requests also bypass routing.

The model is instructed to select the least expensive sufficient pipeline: Fast for ordinary dense + FTS hybrid recall, fusion, and final rerank; Research for Summary/Outline/PageIndex tree navigation without ordinary hybrid, Graph, or ordinary rerank; and Deep for ordinary hybrid recall plus Graph expansion, followed by one unified final rerank. Selection is not implemented by hard-coded CJK/language, query-length, word-count, or keyword rules. A timeout, provider failure, invalid response, or model-identity mismatch safely degrades to the published defaultMode and is recorded in the trace; it never falls back to the removed heuristic.

Response headers:

• x-query-run-id: server-generated UUID used as the durable AnswerTrace.id, retrieval lease ID, session query ID, and query activity resource ID. Use this value with GET /queries/{traceId}.
• x-trace-id: HTTP request correlation ID. It can originate from the caller and is deliberately separate from the durable query-run ID; do not use it as the AnswerTrace resource ID.
• x-session-id: generated or reused query session ID. A successful streamed query has a resolved session even when the request omitted sessionId.

Responses:

• 200 (text/event-stream):
  • answer.delta { delta, traceId }: one generated answer fragment. traceId is the durable query-run ID.
  • answer.done { finishReason, metadata?, traceId }: the single successful terminal frame. Production finish reasons are retrieval-evidence and no-retrieval-evidence.
  • answer.error { error, traceId }: the terminal failure frame. No answer.done follows it.
• 400 invalid request or retrieval-profile/mode mismatch; 404 space not found; 409 query admission rejected while deletion is active; 503 query generation, published runtime snapshot, embedding profile, projection snapshot, or required retrieval capability unavailable; 401/403.

answer.done.metadata is generator-dependent and can contain generator, mode, reasoning model, provider, providerFinishReason, opaque providerMetadata, topScore, citations, the complete evidenceBundle, multimodal evidence/answer metadata, and the same projectionSnapshot, retrievalProfile, retrieval plan, and retrieval metrics persisted in the AnswerTrace.

The gateway buffers the terminal answer.done frame until the AnswerTrace transaction commits. If the trace commit fails, the client receives answer.error instead of a false successful terminal frame. A disconnect before terminal ownership is claimed normally cancels the run without creating an AnswerTrace. After a successful trace commit, failed-query capture is best-effort and currently recognizes no-retrieval-evidence and configured low-confidence results.

Internal trace-step events are collected for AnswerTrace persistence and are never emitted as SSE frames. Answer deltas may arrive before the terminal persistence fence; after any generation, lease, or trace-persistence failure the stream emits answer.error when the client is still connected and then closes while retaining HTTP status 200 for the already-open SSE response.

GET /queries/{traceId}

Description: Fetch the durable retrieval/generation execution trace for a query. This is an execution trace, not a replayable copy of the generated answer. Auth: Bearer; scope knowledge-spaces:read. Path params: traceId (uuid). Responses:

• 200: AnswerTrace { id, knowledgeSpaceId, query, mode: enum(fast|deep|research|auto), createdAt, evidenceBundleId?, steps: [{ name, status: enum(ok|error|skipped), startedAt, endedAt?, metadata }] }. New online-query traces store the concrete resolved mode (fast|research|deep) at the top level; auto remains readable in the schema for historical records.
• 404; 401/403.

createdAt is the terminal trace-recording time, not the query admission time. Public responses omit the internal creator subjectId, permission-snapshot ID/revision/access channel, and database completed flag. A trace is readable only by its original authenticated subject while the stored permission snapshot, current knowledge-space read access, API-key binding (when applicable), and all referenced node/document/asset visibility checks still pass. Hidden, deleted, legacy-unowned, or unresolved-evidence traces fail closed with 403 or 404.

Online queries normally persist these steps:

• query.route: routing provenance with requestedMode, concrete resolvedMode, resolver (explicit, llm, or fallback), selectionSource, published reasoning-model/profile identity, prompt version, bounded provider/usage metadata, duration, and a degraded flag plus safe error class when Auto falls back. The step is persisted but is not emitted as an SSE frame. Explicit modes and omitted-mode defaults record routing without making an LLM call.
• query.embed (Fast and Deep only): durationMs, observed embedding model, observed dimension, and immutable vectorSpaceId. Research does not call the embedding capability and omits this step.
• query.retrieve: durationMs, itemCount, optional immutable projectionSnapshot, published retrievalProfile, resolved retrieval plan, and retrieval metrics.
• query.answer: durationMs, answerChars, synthesis, and, for LLM generation, model, provider, and providerFinishReason. A failed multimodal attempt followed by a successful text fallback can produce both an error and an ok query.answer step.
• query.generate: terminal summary with eventCount, optional finishReason, and the complete terminal generator metadata. Its status is authoritative for the database completed state.

The retrieval plan contains { strategyVersion, requestedMode, resolvedMode, queryLanguage, topK, denseTopK, ftsTopK, fusionLimit, rerankCandidateLimit }. The retrievalProfile contains the non-secret published configuration that governed the run: { revision, defaultMode, topK, scoreThreshold, reasoningModel, rerank }, including model pluginId, provider, and model identifiers but no plugin credentials. The projectionSnapshot contains { publicationId, fingerprint, headRevision, projectionVersion }.

Retrieval metrics use a shared shape. Common fields include dense/FTS/fusion candidate counts and latencies, final candidate count, permission/metadata/projection/score-threshold filtered counts, rerank candidates and latency, multimodal/image/table/visual candidate counts, degradation flags, and totalMs. Mode-specific fields are:

• Fast: ordinary dense + FTS hybrid recall and candidate fusion, followed by the single final rerank pass when reranking is enabled by the published profile.
• Research: PageIndex/Outline/Summary fields such as pageIndexMatchedNodes, pageIndexOpenedRanges, scanned outlines/nodes, candidate truncation, PageIndex score version, Summary candidates/selected sections, and threshold-filtered candidates. Dense/FTS/rerank plan limits are zero and no Graph expansion is used.
• Deep: ordinary hybrid fields plus graphExpansionSeeds, traversed entities, relations, candidates, latency, and timeout state, followed by the single final rerank pass when reranking is enabled by the published profile.

Graph expansion, PageIndex, and rerank currently appear inside query.retrieve.plan/metrics, not as separate trace steps. A stage step is emitted only after that stage completes; an embedding or retrieval exception before emission can therefore leave only the terminal query.generate:error step. completed=true means execution reached a successful terminal summary: a no-retrieval-evidence result is still completed, and a recovered intermediate error does not make the terminal query fail.

AnswerTrace deliberately does not persist the generated answer text, SSE delta fragments, prompt/messages, session ID, active document/entity context, raw query vector, normalized token usage/cost, or exception stack. Token/usage data is present only when a provider places it in opaque providerMetadata. Clients that require answer replay or audit must persist the SSE answer content separately.

steps[].metadata is an open JSON object and the direct trace response returns it after the access checks above. It can contain complete evidence text, provider and multimodal metadata, internal projection identifiers, and aggregate filtered-candidate diagnostics; clients must treat it as sensitive authorized content.

The terminal EvidenceBundle embedded in query.generate.metadata.evidenceBundle has this shape:

{ id, query, traceId?, createdAt, state: enum(answerable|partial|not-enough-evidence|conflict|permission-limited), items: [{ nodeId, text, score, scores: { retrieval, rerank?, freshness?, final }, freshness, citations: [{ documentAssetId, documentVersion, artifactHash?, pageNumber?, sectionPath, startOffset?, endOffset? }], conflicts, metadata }], missingEvidence: [{ expectedEvidenceId?, reason, text, metadata }] }.

For an online query the same complete bundle is stored in the terminal step metadata and in the scoped evidence_bundles storage; evidenceBundleId identifies that persisted bundle.

GET /queries/{traceId}/evidence

Description: List the evidence supporting an answer trace (paginated virtual-tree listing). Auth: Bearer; scope knowledge-spaces:read. Path params: traceId (uuid). Query (strict): cursor (string, optional); limit (int 1–100, optional, default 25). Responses:

• 200: KnowledgeFS list { path, truncated, items: [{ kind: "resource", name: nodeId, path, resourceType: "node", targetId: nodeId, metadata: { citationCount, conflictCount, freshness, score, scores } }], nextCursor? }.
• 400; 404; 401/403.

This is a compact virtual-tree projection. It does not repeat evidence text or citation arrays; the authorized direct AnswerTrace currently contains the complete embedded EvidenceBundle.

GET /queries/{traceId}/conflicts

Description: List conflicting evidence for an answer trace (paginated virtual-tree listing). Auth: Bearer; scope knowledge-spaces:read. Path params: traceId (uuid). Query (strict): cursor; limit (int 1–100, default 25). Responses: 200 KnowledgeFS list with resource entries containing { nodeId, reason, severity } metadata and a target node ID; 400; 404; 401/403.

GET /queries/{traceId}/missing

Description: List evidence gaps (missing/not-found evidence) for an answer trace. Auth: Bearer; scope knowledge-spaces:read. Path params: traceId (uuid). Query (strict): cursor; limit (int 1–100, default 25). Responses: 200 KnowledgeFS list with evidence entries containing the missing-evidence reason plus its metadata and expectedEvidenceId when present; 400; 404; 401/403.

GET /knowledge-spaces/{id}/quality/traces

Description: List subject-owned, candidate-authorized AnswerTrace summaries for the Quality history view. Auth: Bearer; scope knowledge-spaces:read; current knowledge-space read authorization is also required. Path params: id (uuid). Query (strict): cursor (opaque string, optional); from/to (datetime, optional); limit (int 1–100, optional, default 50); mode (enum auto|deep|fast|research, optional); query (trimmed string 1–500, optional); status (enum completed|failed, optional). Responses:

• 200: { items: QualityAnswerTraceSummary[], nextCursor? }, where each summary is { id, query, mode, createdAt, completed, evidenceBundleId?, evidenceState?, finalScore?, scores: { retrieval?, rerank?, final? }, profile: { embeddingModel?, embeddingVectorSpaceId?, reasoningModel?, rerankModel?, retrievalProfileRevision?, projectionPublicationId?, projectionVersion? }, stages: [{ name, status, candidateCount? }] }.
• 400; 404; 503 Quality runtime unavailable; 401/403.

completed represents terminal execution success, not evidence answerability. This endpoint is the paginated/searchable summary view; use GET /queries/{traceId} for the authorized full execution trace. Quality replay can also create AnswerTrace-shaped stage records without a terminal query.generate step or EvidenceBundle, so consumers must not assume every history row has the online-query step sequence.

Compatibility note: the current status filter treats any trace containing an error step as failed, even when a later query.generate:ok makes completed true. Consequently, a recovered multimodal-to-text fallback can return completed: true while matching status=failed; the two filters are not yet a strict partition of terminal execution state.

PATCH /knowledge-spaces/{id}/quality/traces/{traceId}/missing/{itemKey}

Description: Create or update the review state of one missing-evidence item with optimistic revision checking. Auth: Bearer; scope knowledge-spaces:write; the referenced trace must remain subject-owned and currently visible. Path params: id (uuid); traceId (uuid); itemKey (sha256: followed by 64 lowercase hex characters). Body (application/json, strict): { expectedRevision: int>=0, status: enum(active|dismissed), reason?: string 1–2000 }. Responses:

• 200: MissingEvidenceReview { id, knowledgeSpaceId, itemKey, status, reason?, revision, actorSubjectId, createdAt, updatedAt }.
• 400; 404; 409 revision conflict; 503 Quality runtime unavailable; 401/403.

GET /knowledge-spaces/{id}/quality/traces/{traceId}/missing/{itemKey}/history

Description: Fetch the immutable review history for one missing-evidence item. Auth: Bearer; scope knowledge-spaces:read; the referenced trace must remain subject-owned and currently visible. Path params: same as the missing-evidence review endpoint. Responses:

• 200: { items: [{ id, action, actorSubjectId, fromStatus?, toStatus, reason?, revision, createdAt }] }.
• 400; 404; 503 Quality runtime unavailable; 401/403.

POST /knowledge-spaces/{id}/golden-questions

Description: Create a golden (reference) question for evaluation. Auth: Bearer; scope knowledge-spaces:write. Path params: id (uuid). Body (application/json, strict): question (string 1–4000, required); expectedEvidenceIds (uuid[], optional, default []); tags (string[1–80][], optional, default []); metadata (object, optional, default {}). Responses:

• 201: GoldenQuestion { id, knowledgeSpaceId, question, expectedEvidenceIds: uuid[], tags: string[], metadata, createdAt, updatedAt }.
• 404; 429 capacity; 401/403.

GET /knowledge-spaces/{id}/golden-questions

Description: List golden questions (cursor-paginated). Auth: Bearer; scope knowledge-spaces:read. Path params: id (uuid). Query (strict): cursor (optional); limit (int ≥1, optional, default 100). Responses: 200 { items: GoldenQuestion[], nextCursor? }; 400; 404; 401/403.

GET /knowledge-spaces/{id}/golden-questions/{questionId}

Description: Fetch a single golden question. Auth: Bearer; scope knowledge-spaces:read. Path params: id (uuid); questionId (uuid). Responses: 200 GoldenQuestion; 404; 401/403.

PATCH /knowledge-spaces/{id}/golden-questions/{questionId}

Description: Partially update a golden question. Auth: Bearer; scope knowledge-spaces:write. Path params: id (uuid); questionId (uuid). Body (application/json, strict, all optional): question (1–4000); expectedEvidenceIds (uuid[]); tags (string[1–80][]); metadata (object). Responses: 200 updated GoldenQuestion; 404; 401/403.

POST /knowledge-spaces/{id}/golden-questions/{questionId}/annotations

Description: Record a human evaluation annotation (answer correctness + per-evidence relevance). Auth: Bearer; scope knowledge-spaces:write. Path params: id (uuid); questionId (uuid). Body (application/json, strict): answerCorrectness (enum correct|incorrect|not-answerable|partially-correct, required); evidenceRelevance (array ≤50, optional, default []) each { evidenceId: uuid, relevant: boolean, note?: string 1–1000 }; note (string 1–1000, optional). Responses: 200 annotated GoldenQuestion (annotation in metadata); 400; 404; 401/403.

DELETE /knowledge-spaces/{id}/golden-questions/{questionId}

Description: Delete a golden question. Auth: Bearer; scope knowledge-spaces:write. Path params: id (uuid); questionId (uuid). Responses: 204; 404; 401/403.

POST /knowledge-spaces/{id}/production-bad-cases

Description: Capture a production answer trace as a bad case, queued (as a golden question) for review. Auth: Bearer; scope knowledge-spaces:write. Path params: id (uuid). Body (application/json, strict): traceId (uuid, required); reason (string 1–1000, optional); tags (string[1–80][] ≤20, optional, default []). Responses: 201 GoldenQuestion; 404 space/trace not found; 429 capacity; 401/403.

PATCH /knowledge-spaces/{id}/failed-queries/{failedQueryId}

Description: Annotate a failed query — retrieval-miss promotes it to a golden question, coverage-gap marks it annotated, irrelevant dismisses it. Auth: Bearer; scope knowledge-spaces:write. Path params: id (uuid); failedQueryId (uuid). Body (application/json, strict): verdict (enum retrieval-miss|coverage-gap|irrelevant, required); expectedEvidenceIds (uuid[] ≤100, optional) — carried onto the promoted golden question; note (string ≤2000, optional). Responses:

• 200: FailedQuery { id, knowledgeSpaceId, query, mode: enum(fast|deep|research|auto), trigger: enum(no-retrieval-evidence|low-confidence|abstained), status: enum(pending-triage|triaged|pending-annotation|annotated|dismissed|promoted), metadata, answerTraceId?, createdAt, updatedAt }.
• 404; 401/403.

GET /knowledge-spaces/{id}/failed-queries/metrics

Description: Failed-query counts by status plus the golden-question promotion rate. Auth: Bearer; scope knowledge-spaces:read. Path params: id (uuid). Responses:

• 200: { total: number, promotionRate: number, byStatus: { "pending-triage", triaged, "pending-annotation", annotated, dismissed, promoted: number } }.
• 404; 401/403.

GET /knowledge-spaces/{id}/failed-queries/clusters

Description: Group failed queries into clusters (most frequent first) with a representative per cluster. Auth: Bearer; scope knowledge-spaces:read. Path params: id (uuid). Query (strict): limit (int 1–1000, optional, default 200); status (enum, optional). Responses:

• 200: { clusters: [{ clusterKey: string, count: number, failedQueryIds: string[], representative: FailedQuery }] }.
• 404; 401/403.

POST /knowledge-spaces/{id}/failed-queries/triage

Description: Run the relevance-triage runner over a batch of pending failed queries, auto-assigning verdicts. Auth: Bearer; scope knowledge-spaces:write. Path params: id (uuid). Query (strict): limit (int 1–200, optional). Responses:

• 200: { triaged: number, verdicts: { "retrieval-miss", "coverage-gap", irrelevant, uncertain: number } }.
• 404; 501 relevance triage not configured; 401/403.

GET /knowledge-spaces/{id}/failed-queries

Description: List failed queries (cursor-paginated), optionally filtered by status. Auth: Bearer; scope knowledge-spaces:read. Path params: id (uuid). Query (strict): cursor (optional); limit (int 1–200, optional, default 50); status (enum, optional). Responses: 200 { items: FailedQuery[], nextCursor? }; 400; 404; 401/403.

---

Data sources, graph, semantic & research

Source object & conventions

• Source = { id, knowledgeSpaceId, name, type: enum(upload|object-storage|connector|web), uri, status: enum(active|syncing|error|disabled), permissionScope: string[], metadata, version: int≥1, createdAt, updatedAt }.
• Optimistic locking: version is bumped on every write. Pass it back as expectedVersion on PATCH to fail with 409 instead of overwriting a concurrent modification.
• Scheduled sync: set metadata.syncPolicy to {"everyHours": N} (1–720) or {"dailyAt": ["HH:MM", …], "utcOffset": "±HH:MM"?}. Invalid policies are rejected with 400 at create/update. A background scheduler (multi-replica safe; KNOWLEDGE_SOURCE_SYNC* env) then re-syncs due sources: web → re-crawl with content-hash dedup, connector pages → re-import previously imported pages whose lastEditedTime changed, drive → re-download previously imported files. The scheduler records progress under metadata.syncState { lastSyncAt, lastSyncStatus: ok|error, lastSyncError?, nextSyncAt, syncStartedAt? }.
• Reserved metadata keys (managed by the platform; user PATCHes should carry them through): tenantId (auto-stamped on create/update), sync (last sync summary), crawled, imported, importedFiles (per-source sync state), syncState.

POST /knowledge-spaces/{id}/sources

Description: Register a new data source (upload/object-storage/connector/web). Auth: Bearer; scope knowledge-spaces:write. Path params: id (uuid). Body (application/json, strict): name (string 1–200, required); type (enum upload|object-storage|connector|web, required); uri (string, min 1, required); status (enum active|syncing|error|disabled, optional); permissionScope (string[], optional); metadata (object, optional) — connector/provider config (e.g. pluginId, provider, datasource, credentials, parameters) and optionally syncPolicy (see conventions above). The owning tenantId is stamped into metadata automatically. Responses:

• 201: Source (shape above, version: 1).
• 400 invalid metadata.syncPolicy; 404; 429 capacity; 401/403.

GET /knowledge-spaces/{id}/sources

Description: List a space's sources (cursor-paginated). Auth: Bearer; scope knowledge-spaces:read. Path params: id (uuid). Query (strict): limit (int 1–200, optional, default 50); cursor (optional). Responses: 200 { items: Source[], nextCursor? }; 400; 404; 401/403.

GET /knowledge-spaces/{id}/sources/{sourceId}

Description: Fetch a single source. Auth: Bearer; scope knowledge-spaces:read. Path params: id (uuid); sourceId (uuid). Responses: 200 Source; 404; 401/403.

PATCH /knowledge-spaces/{id}/sources/{sourceId}

Description: Update a source's mutable fields (name/status/metadata), optionally guarded by optimistic locking. Auth: Bearer; scope knowledge-spaces:write. Path params: id (uuid); sourceId (uuid). Body (application/json, strict, all optional): name (1–200); status (enum); metadata (object, replaces wholesale — tenantId is re-stamped automatically); expectedVersion (int ≥1) — the version from your last read; when provided, a concurrent modification makes the update fail with 409 instead of overwriting it. Responses:

• 200: updated Source (version bumped).
• 400 invalid metadata.syncPolicy; 404; 409 concurrent modification (expectedVersion mismatch); 401/403.

DELETE /knowledge-spaces/{id}/sources/{sourceId}

Description: Delete a source and, by default, cascade-delete its documents. Auth: Bearer; scope knowledge-spaces:write. Path params: id (uuid); sourceId (uuid). Query (strict): documents (enum cascade|keep, optional, default cascade). Responses: 204; 404; 401/403.

POST /knowledge-spaces/{id}/sources/{sourceId}/crawl

Description: Trigger a website crawl for a web source and materialize crawled pages into documents, with content-hash dedup: pages whose content is byte-identical to the last crawl are skipped; changed pages are re-materialized and their superseded document is cascade-deleted (replaced); new pages are imported. Per-URL state lives in metadata.crawled { [url]: { documentAssetId, sha256 } }. Auth: Bearer; scope knowledge-spaces:write. Path params: id (uuid); sourceId (uuid). Body: None (target from the source's uri/metadata). Responses:

• 200: WebsiteCrawlResult { pages: [{ sourceUrl, content, title?, description? }], status?, total?, completed?, failed?, imported?, replaced?, skipped? } — imported = newly materialized documents, skipped = unchanged pages deduped by content hash, replaced = superseded documents deleted for changed pages.
• 400 not a web source; 404; 501 connector not configured; 502 crawl failed; 401/403.

GET /knowledge-spaces/{id}/sources/{sourceId}/pages

Description: List authorized pages from an online-document connector (e.g. Notion), grouped by workspace. Auth: Bearer; scope knowledge-spaces:read. Path params: id (uuid); sourceId (uuid). Responses:

• 200: OnlineDocumentPages { workspaces: [{ workspaceId?, workspaceName?, total?, pages: [{ pageId, pageName, type, parentId?, lastEditedTime? }] }] }.
• 400 not a connector; 404; 501 connector not configured; 502 provider failed; 401/403.

POST /knowledge-spaces/{id}/sources/{sourceId}/test

Description: Validate the stored credentials for a source against its provider. Auth: Bearer; scope knowledge-spaces:write. Path params: id (uuid); sourceId (uuid). Responses: 200 { valid: boolean, error? }; 404; 501 tester not configured; 401/403.

POST /knowledge-spaces/{id}/sources/{sourceId}/import

Description: Import selected online-document pages as documents; re-import skips pages whose lastEditedTime is unchanged. Imported pages are recorded in metadata.imported { [pageId]: { documentAssetId, lastEditedTime? } }, which scheduled sync refreshes (never-imported pages are not auto-added — selection stays manual). Auth: Bearer; scope knowledge-spaces:write. Path params: id (uuid); sourceId (uuid). Body (application/json, strict): pages (array 1–200) each { pageId (min 1, required), workspaceId (min 1, required), type (min 1, required), name? (1–200), lastEditedTime? (min 1) }. Responses:

• 200: SourceImportResult { documents: [{ documentAssetId, filename }], failed: [{ filename, error }], skipped: string[] }.
• 400 not a connector; 404; 501; 502; 401/403.

GET /knowledge-spaces/{id}/sources/{sourceId}/files

Description: Browse files from an online-drive connector (e.g. S3/Drive), grouped by bucket. Auth: Bearer; scope knowledge-spaces:read. Path params: id (uuid); sourceId (uuid). Query (strict): bucket (optional); prefix (optional); maxKeys (int 1–1000, optional). Responses:

• 200: OnlineDriveFiles { buckets: [{ bucket?, isTruncated?, files: [{ id, name, type, size? }] }] }.
• 400 not a drive connector; 404; 501; 502; 401/403.

POST /knowledge-spaces/{id}/sources/{sourceId}/import-files

Description: Import selected online-drive files as documents. Successfully imported files are recorded in metadata.importedFiles { [fileId]: { name, bucket?, mimeType? } }, which scheduled sync re-downloads. Auth: Bearer; scope knowledge-spaces:write. Path params: id (uuid); sourceId (uuid). Body (application/json, strict): files (array 1–200) each { id (min 1, required), name (1–255, required), bucket?, mimeType? }. Responses: 200 SourceImportResult { documents, failed, skipped }; 400; 404; 501; 502; 401/403.

GET /knowledge-spaces/{id}/graph/traverse

Description: Bounded breadth-limited traversal of the knowledge graph from a seed entity. Auth: Bearer; scope knowledge-spaces:read. Path params: id (uuid). Query (strict): entityId (uuid, required); depth (int 1–2, optional, default 2); fanout (int 1–50, optional, default 20); maxNodes (int 1–200, optional, default 50); timeoutMs (int 1–5000, optional, default 250). Responses:

• 200: { entities: GraphEntity[], relations: GraphRelation[], truncated, metrics: { depthReached, elapsedMs, exploredRelations, fanout, maxDepth, maxNodes, timedOut } }. GraphEntity { id, knowledgeSpaceId, name, canonicalKey, aliases: string[], type: enum(date|metric|organization|person|policy|product|term), confidence, depth, extractionVersion, permissionScope: string[], sourceNodeIds: string[], metadata, createdAt, updatedAt }. GraphRelation { id, knowledgeSpaceId, subjectEntityId, objectEntityId, type: enum(contradicts|defines|depends_on|mentions|references|supersedes), confidence, depth, extractionVersion, permissionScope, sourceNodeIds, metadata, createdAt, updatedAt }.
• 404 space/seed entity not found; 401/403.

POST /knowledge-spaces/{id}/semantic-views/topic/materialize

Description: Materialize a KnowledgeFS topic semantic view (virtual topic path over documents). Auth: Bearer; scope knowledge-spaces:write. Path params: id (uuid). Body (application/json, strict, all optional): topicName (1–120); topicSlug (1–120, kebab-case); generatedVersion (1–120); limit (int 1–100, default 50). Responses: 200 { knowledgeSpaceId, topicName, topicSlug, generatedVersion, documentCount, pathCount }; 400; 404; 401/403.

POST /knowledge-spaces/{id}/semantic-views/entities/extract

Description: Extract & index semantic entities/relations from the space's nodes via the model provider. Auth: Bearer; scope knowledge-spaces:write. Path params: id (uuid). Body (application/json, strict): limit (int 1–100, optional, default 50). Responses: 200 { knowledgeSpaceId, extractionMode: "provider", nodesScanned, nodesUpdated, entitiesExtracted, graphEntitiesIndexed, graphRelationsIndexed }; 400; 404; 401/403.

POST /knowledge-spaces/{id}/semantic-views/communities/materialize

Description: Materialize a KnowledgeFS community semantic view (entity-cluster grouping). Auth: Bearer; scope knowledge-spaces:write. Path params: id (uuid). Body (application/json, strict): generatedVersion (1–120, optional). Responses: 200 { knowledgeSpaceId, generatedVersion, communityCount, entityCount, documentCount, pathCount }; 400; 404; 401/403.

POST /research-tasks/plan

Description: Produce a dry-run plan (cost/latency/retrieval estimates) for a research task without executing. Auth: Bearer; scope knowledge-spaces:read. Body (application/json, strict): knowledgeSpaceId (uuid, required); query (string 1–16000, required); mode (enum auto|deep|fast|research, optional); topK (int 1–50, optional); budgetUsd (number ≥0, optional).

An omitted mode uses the published defaultMode. An explicit auto is resolved through the published reasoning model before the deterministic dry-run planner runs; retrievalPlan preserves requestedMode: "auto" and reports the concrete resolvedMode.

Responses:

• 200: ResearchTaskDryRunPlan { knowledgeSpaceId, query, strategyVersion, budget: { budgetUsd?, exceedsBudget, remainingBudgetUsd? }, estimates: { costUsd: { currency, estimated, min, max }, inputTokens, outputTokens, totalTokens, latencyMs: { p50, p95 }, retrievalSteps, scannedResources, toolCalls, cacheHitProbability }, retrievalPlan: { requestedMode, resolvedMode, queryLanguage, topK, denseTopK, ftsTopK, fusionLimit, rerankCandidateLimit, strategyVersion }, steps: [{ name: enum(analyze|generate|inspect|plan|retrieve), estimatedInputTokens, estimatedOutputTokens, estimatedToolCalls, estimatedLatencyMs, estimatedCostUsd }] }.
• 400; 404; 401/403.

POST /research-tasks

Description: Create and enqueue an asynchronous research task job. Auth: Bearer; scope knowledge-spaces:write. Body (application/json): knowledgeSpaceId (uuid, required); query (string 1–16000, required); mode (enum auto|deep|fast|research, optional); topK (int 1–50, optional); budgetUsd (number ≥0, optional); limits (object, optional) { maxRetrievalSteps?, maxScannedResources?, maxToolCalls?, timeoutMs? }; metadata (object, optional); permissionScope (object, optional).

For an explicit auto, creation authorizes the caller, freezes the published publication/profile tuple, invokes that profile's reasoning model once, and persists the concrete mode plus bounded routing provenance. Queue retries and worker restarts reuse the persisted decision and never reclassify the query. Router failure uses the frozen profile's defaultMode; omitting mode uses that default directly without an LLM call. Auto creation requires a query-ready published runtime snapshot and returns 503 when that immutable tuple is unavailable; the legacy mutable-profile compatibility path does not admit Auto.

Responses:

• 201: ResearchTaskJob { id, tenantId, subjectId, knowledgeSpaceId, queueJobId, query, stage: enum(queued|planning|retrieving|analyzing|generating|completed|failed|canceled), limits?, budgetUsd?, cost: { totalUsd, budgetUsd?, budgetExceeded?, entries: [{ step, provider, costUsd, usage, recordedAt: number }] }, error?, createdAt: number, updatedAt: number, completedAt?: number }.
• 400; 404; 422 limits exceeded { error, violations: [{ limit, limitValue, estimatedValue }] }; 401/403.

GET /research-tasks/{id}

Description: Get the current status/result of a research task job. Auth: Bearer; scope knowledge-spaces:read. Path params: id (string, min 1). Responses: 200 ResearchTaskJob; 404; 401/403.

GET /research-tasks/{id}/partials

Description: List a research task's partial evidence bundles (cursor-paginated). Auth: Bearer; scope knowledge-spaces:read. Path params: id (string, min 1). Query (strict): limit (int 1–100, optional, default 25); cursor (optional). Responses:

• 200: { items: [{ tenantId, knowledgeSpaceId, researchTaskJobId, sequence: int>0, evidenceBundle }], nextCursor? }. EvidenceBundle { id, query, state: enum(answerable|partial|not-enough-evidence|conflict|permission-limited), items: [{ nodeId, text, score: 0–1, scores, freshness, citations[], conflicts[], metadata }], missingEvidence: [{ text, reason: enum(not-retrieved|permission-filtered|stale|conflict|unknown), expectedEvidenceId?, metadata }], traceId?, createdAt }.
• 404; 401/403.

GET /research-tasks/{id}/events

Description: Stream research task progress as SSE. Auth: Bearer; scope knowledge-spaces:read. Path params: id (string, min 1). Query (strict): limit (int 1–100, optional, default 25); cursor (optional). Responses: 200 (text/event-stream) progress event frames; 404; 401/403.

DELETE /research-tasks/{id}

Description: Request cancellation of an in-flight research task job. Auth: Bearer; scope knowledge-spaces:write. Path params: id (string, min 1). Responses: 200 ResearchTaskJob (stage canceled); 404; 409 already terminal; 401/403.

---

System, policy, KnowledgeFS & agent workspace

GET /health

Description: Platform runtime + per-component health. Auth: None (public). Responses: 200 { ok: boolean, runtime: enum(cloudflare-workers|node-docker), components: Record<string, boolean> }.

GET /openapi.json

Description: The machine-readable OpenAPI 3 document for the whole API (served via app.doc). Auth: None (public). Responses: 200 OpenAPI JSON document.

GET /bulk-jobs/{id}

Description: Progress for a bulk document operation job. Auth: Bearer; scope knowledge-spaces:read. Path params: id (string, min 1). Responses:

• 200: { id, knowledgeSpaceId, type: enum(document_upload|document_delete|document_reindex), status: enum(running|completed|failed), totalItems, completedItems, failedItems, failedItemIds: string[], createdAt, updatedAt }.
• 404; 503 dependencies unavailable; 401/403.

GET /retention-policy

Description: The tenant-level retention policy. Auth: Bearer; scope knowledge-spaces:read. Responses:

• 200: RetentionPolicy { id, tenantId, knowledgeSpaceId: uuid|null, scope: enum(tenant|knowledge_space), answerTraceRetentionDays: int>0, evidenceCacheRetentionDays: int>0, inactiveProjectionRetentionDays: int>0, parseArtifactVersions: int>0, rawDocumentRetentionDays: int>0|null, sessionInactivityMinutes: int>0, createdAt, updatedAt }.
• 401/403.

answerTraceRetentionDays is the operational cutoff consumed by bounded asynchronous retention cleanup. Updating the policy does not synchronously delete traces, and a trace can become unreadable earlier when its permission snapshot, current content visibility, or knowledge-space lifecycle state no longer passes authorization.

The default operational policy is 90 days for AnswerTrace, 7 days for evidence cache, 30 days for inactive projections, three parse-artifact versions, no raw-document expiry, and 30 minutes of session inactivity. Tenant and knowledge-space policies are stored independently; an absent knowledge-space policy receives its own defaults rather than inheriting the tenant row. The manifest field retentionPolicy.traceRetentionDays is a separate manifest value; AnswerTrace cleanup uses this API's answerTraceRetentionDays.

Retention policy routes are declarative and there is no public synchronous cleanup endpoint. A deployment must schedule the bounded retention workers for a configured cutoff to take effect.

PATCH /retention-policy

Description: Update the tenant-level retention policy. Auth: Bearer; scope knowledge-spaces:write. Body (application/json, strict, all optional): answerTraceRetentionDays, evidenceCacheRetentionDays, inactiveProjectionRetentionDays, parseArtifactVersions, sessionInactivityMinutes (each int>0); rawDocumentRetentionDays (int>0|null). Responses: 200 updated RetentionPolicy; 400; 401/403.

GET /knowledge-spaces/{id}/retention-policy

Description: The retention policy for a specific knowledge space. Auth: Bearer; scope knowledge-spaces:read. Path params: id (uuid). Responses: 200 RetentionPolicy (scope may be knowledge_space); 404; 401/403.

PATCH /knowledge-spaces/{id}/retention-policy

Description: Update the retention policy for a specific knowledge space. Auth: Bearer; scope knowledge-spaces:write. Path params: id (uuid). Body (application/json, strict): same fields as PATCH /retention-policy. Responses: 200 updated RetentionPolicy; 400; 404; 401/403.

KnowledgeFS virtual filesystem — the /fs/* routes browse a virtual tree over the space's sources/knowledge/evidence/workspaces. path (and oldPath/newPath) must match ^/(sources|knowledge|evidence|workspaces)(/…)*$. All query objects are strict; consistencyClass ∈ path-consistent|snapshot-consistent|cache-consistent|eventual-preview.

GET /knowledge-spaces/{id}/fs/ls

Description: List direct children of a KnowledgeFS virtual directory. Auth: Bearer; scope knowledge-spaces:read. Path params: id (uuid). Query (strict): path (required, namespaced); limit (int ≥1, required); cursor (optional); consistencyClass (optional). Responses:

• 200: { path, items: [{ kind: enum(directory|resource), name, path, metadata, resourceType?: enum(source|document|node|artifact|evidence|workspace), targetId?, version? }], truncated, nextCursor?, consistencyClass?, preview? }.
• 400; 404; 401/403.

GET /knowledge-spaces/{id}/fs/tree

Description: Recursive KnowledgeFS directory tree. Auth: Bearer; scope knowledge-spaces:read. Path params: id (uuid). Query (strict): path (required); limit (int ≥1, required); depth (int 1–8, optional); cursor (optional); consistencyClass (optional). Responses: 200 { path, root: <nested tree>, truncated, nextCursor?, consistencyClass?, preview? }; 400; 404; 401/403.

GET /knowledge-spaces/{id}/fs/grep

Description: Scoped full-text search across KnowledgeFS content. Auth: Bearer; scope knowledge-spaces:read. Path params: id (uuid). Query (strict): q (string 1–4000, required); path (required); limit (int ≥1, required); cursor (optional); consistencyClass (optional); timeoutMs (int 1–10000, optional). Responses:

• 200: { path, matches: [{ kind: enum(node|segment), path, snippet, startOffset, endOffset, metadata, nodeId?, segmentId? }], truncated, nextCursor? }.
• 400; 404; 401/403.

GET /knowledge-spaces/{id}/fs/find

Description: Search KnowledgeFS entries by name/metadata/resource-type. Auth: Bearer; scope knowledge-spaces:read. Path params: id (uuid). Query (strict): path (required); limit (int ≥1, required); cursor (optional); consistencyClass (optional); nameContains (1–240, optional); metadataKey (1–120, optional); metadataValue (1–4000, optional); resourceType (enum, optional). Responses: 200 (same shape as fs/ls); 400; 404; 401/403.

GET /knowledge-spaces/{id}/fs/diff

Description: Text (and optional semantic) diff between two KnowledgeFS paths. Auth: Bearer; scope knowledge-spaces:read. Path params: id (uuid). Query (strict): oldPath (required); newPath (required); mode (enum line|word, optional); semantic (enum "true"|"false", optional); consistencyClass (optional). Responses:

• 200: { mode, oldPath, newPath, operations: [{ kind: enum(equal|insert|delete), text, oldStart?, oldEnd?, newStart?, newEnd? }], stats: { equal, insert, delete }, semantic?: { summary, changes: [{ category, summary, evidence: string[] }], metadata, model? } }.
• 400; 404; 503 diff unavailable; 401/403.

GET /knowledge-spaces/{id}/fs/open_node

Description: A single citation-ready KnowledgeFS node with its source citation. Auth: Bearer; scope knowledge-spaces:read. Path params: id (uuid). Query (strict): nodeId (uuid, required); consistencyClass (optional). Responses:

• 200: { citation: { documentAssetId, parseArtifactId, artifactHash, sectionPath: string[], startOffset, endOffset, pageNumber? }, node: KnowledgeNode }; KnowledgeNode { id, knowledgeSpaceId, documentAssetId, parseArtifactId, artifactHash, kind: enum(chunk|section|table|image|summary), text, startOffset, endOffset, sourceLocation, permissionScope, metadata, updatedAt? }.
• 404; 401/403.

GET /knowledge-spaces/{id}/fs/cat

Description: Read file content at a KnowledgeFS path. Auth: Bearer; scope knowledge-spaces:read. Path params: id (uuid). Query (strict): path (required); limit (int ≥1, optional); cursor (optional); consistencyClass (optional). Responses: 200 { path, contentType, text, truncated, nextCursor? }; 404; 401/403.

GET /knowledge-spaces/{id}/fs/stat

Description: Metadata for a KnowledgeFS path without reading content. Auth: Bearer; scope knowledge-spaces:read. Path params: id (uuid). Query (strict): path (required); consistencyClass (optional). Responses:

• 200: { path, targetId, resourceType: enum(source|document|node|artifact|evidence|workspace), metadata, contentType?, sha256?, sizeBytes?, version?, parserStatus?: enum(pending|parsed|failed), consistencyClass?, preview? }.
• 404; 401/403.

POST /knowledge-spaces/{id}/fs/write

Description: Overwrite a KnowledgeFS file with new text content. Auth: Bearer; scope knowledge-spaces:write. Path params: id (uuid). Body (application/json, strict): path (required, namespaced); text (string, ≤262144 bytes / 256 KiB, required). Responses: 200 { path, targetId, objectKey, version, bytesWritten, mode: "write" }; 400; 404; 401/403.

POST /knowledge-spaces/{id}/fs/append

Description: Append text to an existing KnowledgeFS file. Auth: Bearer; scope knowledge-spaces:write. Path params: id (uuid). Body (application/json, strict): path (required, namespaced); text (string, ≤256 KiB, required). Responses: 200 { path, targetId, objectKey, version, bytesWritten, mode: "append" }; 400; 404; 401/403.

POST /agent-workspace-snapshots

Description: Create an immutable agent-workspace snapshot (mounts, evidence, command log, source versions). Auth: Bearer; scope knowledge-spaces:write. Body (application/json, strict): knowledgeSpaceId (uuid, required); indexProjection { fingerprint (1–512), projectionIds: string[] } (required); manifestVersion (int>0, default 1); commandLog (array, default []) each { command (1–4000), startedAt, completedAt?, input (default {}), outputSummary? (≤4000), cost? }; evidenceBundles (EvidenceBundle[], default []); mounts (ResourceMount[], default []); pathVersions (array, default []) { virtualPath (1–1000), version (1–512) }; sourceVersions (array, default []) { provider (1–120), providerResourceKey (1–1000), version (1–512) }; traceIds (string[], default []); researchTaskJobId (1–240, optional); metadata (object, default {}). Responses:

• 201: AgentWorkspaceSnapshot { id, tenantId, knowledgeSpaceId, fingerprint (/^snapshot-sha256:[a-f0-9]{64}$/), manifestVersion, commandLog, evidenceBundles, mounts, indexProjection, pathVersions, sourceVersions, permissionSnapshot: { subjectId, tenantId, scopes: string[] }, traceIds, researchTaskJobId?, metadata, createdAt }.
• 400; 404; 401/403.

GET /agent-workspace-snapshots/{id}

Description: Fetch a previously created agent-workspace snapshot. Auth: Bearer; scope knowledge-spaces:read. Path params: id (string, 1–240). Responses: 200 AgentWorkspaceSnapshot; 404; 401/403.

POST /agent-workspace-snapshots/{id}/replay

Description: Re-execute a snapshot's recorded command log and report per-command drift. Auth: Bearer; scope knowledge-spaces:read (this POST maps to read, unlike other POSTs). Path params: id (string, 1–240). Body: None. Responses:

• 200: AgentWorkspaceReplay { id, snapshotId, tenantId, knowledgeSpaceId, startedAt, completedAt, traceId?, summary: { total, matched, changed, failed }, commands: [{ commandIndex, command, status: enum(matched|changed|failed), input, startedAt, completedAt, originalOutputSummary?, replayedOutputSummary?, error? }] }.
• 404; 409 replay failed; 401/403.