Knowledge Management application API

Status: Vanguard qualification | Last reviewed: 2026-10-09

Knowledge responses use Cache-Control: no-store, including artifacts, answers and application errors, so browser caches do not retain an earlier access view. Graph answers include graphRetrieval with candidateUnits, addedUnits, ranked and answerLimit. Large graph candidate sets are ranked within the authorized native document inventory before the final 50-unit answer window is assembled. Selected evidence is not clipped during synthesis.

Knowledge routes use /api/knowledge-agents/{agentId} and require FEATURE_KNOWLEDGE_AGENTS. The live /openapi.json and generated AI Manager integration specification include the Knowledge Management operations. See the implementation guide for preparation, native RAGFlow compatibility and worker setup.

Graph inspection includes original evidence excerpts resolved from native references. Responses contain at most 50 entities, 100 relations and 100 excerpts of 2,000 characters; clipping indicators distinguish a bounded view from the complete saved graph.

Cookie sessions and tenant API tokens use normal Studio authentication. Evaluations are limited to 500 cases per run. Explicitly selected cases must all belong to this agent and remain available; missing or rejected cases cause the request to fail instead of reducing its test denominator. Published queries require AIManager:RunAgents / agents:run; authoring, draft inspection, tests and publication also require ManageAgents / agents:manage and agent edit access. Native connection updates additionally require ManageConfiguration. An unavailable feature returns 404.

Query and MCP

POST /chat accepts:

{
  "question": "Which sources establish the applicable exception?",
  "published": true,
  "filters": {"sourceIds": [], "metadata": {}}
}

The server resolves the published build and query configuration. Authors can instead supply a completed buildId with published: false. Explicit filters can narrow the configured source/date/metadata scope. The response includes the question, retrieval query, answer text, numbered citations, original evidence and source locators, missing information, build identity and timing. Source revocation or revision changes block querying an old release.

POST /mcp implements stateless MCP initialization, tools/list and tools/call. The single tool, ask_knowledge, accepts question and optional filters. It always resolves the current publication. It cannot accept native dataset IDs, credentials or draft build selection. Use a tenant API token with agents:run scope in the consuming MCP tool's Authorization header. Tool execution errors return isError: true; GET does not offer an SSE stream.

Authoring and durable work

Route suffix	Request and behavior
GET /	Workspace, authorized sources, builds, jobs, cases and current publication
POST /config	{config, revision}; optimistic save of the described knowledge schema
POST /sources	Website/upload source and typed metadata; updates require its revision
POST /uploads, PUT /upload/{id}	Reserve {name, contentType, size}, then stream exact encrypted bytes
POST /builds	Freeze source/query configuration and queue a candidate
GET /builds/{id}	100 documents/units per offset, with operation status
GET /builds/{id}/artifact	One nodeId / documentId checkpoint
GET /builds/{id}/graph	Optional node search; bounded native neighborhood plus total counts
GET /builds/{id}/impact	Source/content/preparation differences and affected requirements
POST /jobs/{id}	{action: "cancel"} or {action: "retry"} for a failed job
POST /cases	{value} or {id, revision, value}; typed expectations and review state
POST /cases/import	{cases: [...]}; atomic, up to 500, always candidate state
POST /evaluations	{buildId, caseIds?}; freeze cases and matching query configuration
GET /evaluations/{id}	Answers, judgments, explanations and required-source recall
POST /discovery	content, terminology, transcript or analytics mode
POST /terms/{id}	{revision, reviewState} for source-backed mappings
POST /publish	{buildId, evaluationId}; verify current configuration and required tests
POST /rollback	{historyId}; new publication of an earlier generation, subject to current access
GET/POST /connection	Read masked or update encrypted tenant native connection

Content/terminology discovery requires a completed buildId and an explicit maximumUnits sample, up to 200. Direct transcript discovery accepts text and optional name; it redacts through the shared Analytics preparation before storage and processes overlapping windows. Analytics discovery uses a ready tenant releaseId and up to 1,000 complete conversations. Spoken answers remain unverified. Samples do not establish whole-corpus coverage.

Ordinary JSON bodies are bounded to 4 MiB. Uploads are bounded to 100 MiB and stream through the dedicated PUT route. Native datasets and encrypted originals are retained for candidate inspection; automatic retention cleanup remains follow-up work. Disable scheduling before a schema deployment and resume after migration checks to avoid migration/worker lock contention.

Qualification

The public-corpus expectations are engineering fixtures reviewed against frozen originals. The matching qualification record distinguishes measured results from remaining provider, scale and domain work.