Compose a PRView SourceOpen Issue

Synced from Hive. This page is pulled from hivecommons/hive@v5 during the docs build. Edit the canonical source in the Hive repository.

Dashboard REST API reference — Knowledge

Part of the Dashboard REST API reference; see that page for how auth levels and pkg/<file>:<line> source citations are read and checked. Edit this file for routes in this area and run src/scripts/check-api-reference-citations.sh --fix to resync citations.

MethodPathAuthPurposeSource
GET/api/knowledgeDashboard auth/sessionPaginated knowledge facts: type filter, limit (default 50, max 200; invalid/non-positive values use the default), offset (default 0). Returns enabled, facts, count (this page), total, limit, offset, has_more; ordered by layer then slug. Offsets are not snapshot cursors: concurrent edits may shift pages.pkg/dashboard/api.go:384
GET/api/knowledge/exportDashboard auth/sessionKnowledge Exportpkg/dashboard/api.go:385
POST/mcp/knowledgePublic (read-only) when the dashboard setting or HIVE_PUBLIC_KNOWLEDGE is on; otherwise 404 to a signed-in caller and 401 to one who is notPublic Knowledge MCP endpoint — initialize, tools/list, tools/call for knowledge_search/knowledge_toc/knowledge_get/knowledge_export (docs)pkg/dashboard/api.go:394
GET/api/knowledge/searchDashboard auth/sessionKnowledge Searchpkg/dashboard/api.go:386
GET/api/knowledge/tocDashboard auth/sessionScoped knowledge table of contents: capped, body-free entries (id, title, type, layer, repo, tags, status, confidence, updated, size_bytes, source) plus total/returned/truncated. Query: layers, repos, types, tags (comma-separated), limit (default 50, max 200), include_states (operator opt-in for draft/deprecated/superseded/all), format=prompt with max_chars for a bounded markdown rendering, agent to apply that agent’s knowledge.agent_scopes entry (the other parameters can only narrow it). Approved knowledge only by default (docs)pkg/dashboard/api.go:387
GET/api/knowledge/effectiveDashboard auth/sessionEffective knowledge for one agent (agent required): the agent’s knowledge.agent_scopes entry (unrestricted when it has none) intersected with the request scope (approved only unless include_states is set). Returns scope (resolved scope applied, with configured), included TOC entries, excluded entries each with a reason (lifecycle, layer, repo, type or tag — first failing check, in that order), included_total/excluded_total/included_returned/excluded_returned and truncated; limit caps each list (default 50, max 200) (docs)pkg/dashboard/api.go:388
GET/api/knowledge/entry/{id}Dashboard auth/sessionFull read of one knowledge entry: markdown (front-matter plus body) and the fact. Takes the same scope, include_states and agent query as the table of contents and returns 404 for an entry outside it (docs)pkg/dashboard/api.go:389
POST/api/knowledge/cli-memory/drain-legacyOwner onlyOne-shot drain of the shared home’s legacy Claude memory (/data/home/.claude/projects/*/memory) into state: draft entries in bead-synth-wiki, tagged cli-memory and agent:shared, deduplicated by content hash. Body {"truncate": bool} (default false) empties only files whose every fact is now stored. Returns store, agent, sources, drained, dupes, skipped, truncate, truncated, kept, errors; 409 when the vault is not connected. Audited as knowledge_drain_legacy_memory (docs)pkg/dashboard/api.go:391
GET/api/knowledge/publicDashboard auth/sessionPublic Knowledge MCP sharing status (enabled, tags, source, endpoint URL)pkg/dashboard/api.go:395
PUT/api/knowledge/publicOwner onlyPersist public Knowledge MCP sharing setting; overrides env vars until changedpkg/dashboard/api.go:396
GET/api/knowledge/healthDashboard auth/sessionKnowledge Healthpkg/dashboard/api.go:397
GET/api/knowledge/statsDashboard auth/sessionKnowledge Statspkg/dashboard/api.go:398
GET/api/knowledge/graphDashboard auth/sessionKnowledge Graphpkg/dashboard/api.go:399
GET/api/knowledge/fact-historyDashboard auth/sessionFact Historypkg/dashboard/api.go:400
POST/api/knowledge/createDashboard auth/sessionCreate one fact (title, body, type, tags, layer, confidence, state). state is approved (default) or draft; a draft is written with state: draft into the local channel named by layer (400 when there is none, 409 when its title already names an entry). A request tagged cli-memory must be a draft carrying only cli-memory, agent:&lt;name&gt;, cli:<claude|codex|gemini>, memhash:&lt;hex&gt; and repo:&lt;org&gt;/&lt;repo&gt; tags (400 otherwise)pkg/dashboard/api.go:401
POST/api/knowledge/importDashboard auth/sessionKnowledge Importpkg/dashboard/api.go:402
POST/api/knowledge/promoteDashboard auth/sessionKnowledge Promotepkg/dashboard/api.go:408
GET/api/knowledge/subscriptionsDashboard auth/sessionKnowledge Subs Listpkg/dashboard/api.go:409
POST/api/knowledge/subscriptionsDashboard auth/sessionKnowledge Subs Addpkg/dashboard/api.go:410
DELETE/api/knowledge/subscriptionsDashboard auth/sessionKnowledge Subs Removepkg/dashboard/api.go:411
PUT/api/knowledge/{layer}/{slug}Dashboard auth/sessionKnowledge Updatepkg/dashboard/api.go:412
DELETE/api/knowledge/{layer}/{slug}Dashboard auth/sessionKnowledge Deletepkg/dashboard/api.go:413
GET/api/knowledge/{layer}Dashboard auth/sessionKnowledge Layerpkg/dashboard/api.go:414
GET/api/knowledge/{layer}/{slug}Dashboard auth/sessionKnowledge Factpkg/dashboard/api.go:415
PUT/api/knowledge/enabledOwner onlyKnowledge Togglepkg/dashboard/api.go:416
GET/api/knowledge/bead-synthesizerDashboard auth/sessionBead Synth Statuspkg/dashboard/api.go:417
PUT/api/knowledge/bead-synthesizer/enabledOwner onlyBead Synth Togglepkg/dashboard/api.go:418
GET/api/knowledge/vaultsDashboard auth/sessionVaults Listpkg/dashboard/api.go:419
POST/api/knowledge/vaultsOwner onlyVaults Connectpkg/dashboard/api.go:420
DELETE/api/knowledge/vaultsDashboard auth/sessionVaults Disconnectpkg/dashboard/api.go:421
POST/api/knowledge/vaults/reindexDashboard auth/sessionVaults Reindexpkg/dashboard/api.go:422
GET/api/knowledge/vaults/{name}/factsDashboard auth/sessionVault Factspkg/dashboard/api.go:423
GET/api/config/knowledge/connectorsDashboard auth/sessionKnowledge connectors config (name, type, layer, scope, env/file auth reference) and registered typespkg/dashboard/api.go
PUT/api/config/knowledge/connectorsOwner onlyReplace knowledge.connectors after validation; inline secrets rejectedpkg/dashboard/api.go
GET/api/config/knowledge/connectors/statusDashboard auth/sessionPer-connector status pill, last sync, pages/facts, last error, running and the live progress block (phase, items_done/items_total, current item, started_at; see knowledge-connectors.md), plus the publish mirror statuspkg/dashboard/api.go
POST/api/config/knowledge/connectors/validateOwner onlyDry-run validate one connector entry (no network)pkg/dashboard/api.go
POST/api/config/knowledge/connectors/{name}/syncOwner onlyStart an immediate background sync of one connectorpkg/dashboard/api.go
GET/api/config/knowledge/agent-scopesDashboard auth/sessionPer-agent knowledge scopes (knowledge.agent_scopes: layers, repos, types, tags, include_states) (docs)pkg/dashboard/api.go
PUT/api/config/knowledge/agent-scopesOwner onlyReplace knowledge.agent_scopes after validating layer and state names; persisted and audited as config_knowledge_agent_scopespkg/dashboard/api.go
GET/api/config/knowledge/pipelineOwner onlyScalar bead synthesizer, curator, code map and primer settings, plus the read-only engine, vault paths and primer merge strategy (docs)pkg/dashboard/api.go
PUT/api/config/knowledge/pipelineOwner onlyUpdate those settings after config.ValidateKnowledgePipeline; 0 or empty restores the default; the bead synthesizer switch applies at once, the rest after a restart; audited as config_knowledge_pipelinepkg/dashboard/api.go
GET/api/knowledge/git-sourcesDashboard auth/sessionGit Sources Listpkg/dashboard/api.go:433
POST/api/knowledge/git-sourcesOwner onlyGit Sources Connectpkg/dashboard/api.go:434
DELETE/api/knowledge/git-sourcesOwner onlyGit Sources Disconnectpkg/dashboard/api.go:435
POST/api/knowledge/obsidian/syncDashboard auth/sessionObsidian Syncpkg/dashboard/api.go:436
GET/api/knowledge/documentsDashboard auth/sessionDocuments Listpkg/dashboard/api.go:437
POST/api/knowledge/documentsDashboard auth/sessionDocuments Importpkg/dashboard/api.go:438
GET/api/knowledge/documents/{slug}Dashboard auth/sessionDocument Getpkg/dashboard/api.go:439
DELETE/api/knowledge/documents/{slug}Dashboard auth/sessionDocument Deletepkg/dashboard/api.go:440
POST/api/knowledge/documents/{slug}/reimportDashboard auth/sessionDocument Reimportpkg/dashboard/api.go:441
GET/api/knowledge/context7/searchDashboard auth/sessionContext7 Searchpkg/dashboard/api.go:442
POST/api/knowledge/cleanup-orphansDashboard auth/sessionCleanup Orphanspkg/dashboard/api.go:443
GET/api/knowledge/channelsDashboard auth/sessionKnowledge Channels Listpkg/dashboard/api.go:406
POST/api/knowledge/channelsDashboard auth/sessionKnowledge Channel Createpkg/dashboard/api.go:407
GET/api/knowledge/connectorsDashboard auth/sessionKnowledge connector statuses, each with a live progress block while a sync runs, and publish mirror status ({"connectors": [...], "publish": {...}|null}, see knowledge-connectors.md)pkg/dashboard/api_knowledge_connectors.go:24
POST/api/knowledge/connectors/{name}/syncOwner onlyStart one connector sync now (202; 404 unknown, 409 running)pkg/dashboard/api_knowledge_connectors.go:25
POST/api/knowledge/publish/syncOwner onlyRun a publish mirror batch now (202 with publish status; 503 mirror not running, 409 batch in progress)pkg/dashboard/api_knowledge_connectors.go:26
GET/api/knowledge/connectors/{name}/authDashboard auth/sessionInteractive sign-in state for a connector (Plaud OAuth): connected, account, pending, auth_url; ?refresh=1 re-checks upstream (400 for connector types without interactive sign-in)pkg/dashboard/api_knowledge_connector_auth.go:25
POST/api/knowledge/connectors/{name}/auth/connectOwner onlyStart the connector’s sign-in flow (202 with state incl. auth_url)pkg/dashboard/api_knowledge_connector_auth.go:26
POST/api/knowledge/connectors/{name}/auth/disconnectOwner onlySign out and revoke the connector’s credential upstreampkg/dashboard/api_knowledge_connector_auth.go:27
POST/api/knowledge/connectors/{name}/auth/completeOwner onlyFinish a sign-in from pasted material on a hosted hive: {redirect_url} (the localhost:8199/auth/callback?… URL the browser landed on, forwarded in-pod while the login is pending) or {tokens} (contents of ~/.plaud/tokens-mcp.json); see inbox-voice-sources.mdpkg/dashboard/api_inbox.go:31
GET/api/inboxDashboard auth/sessionInbox items (voice recordings/dictations keyed by (source, id)) with per-destination route state, source connection status, candidate repos and auto-routing settings; see inbox-voice-sources.mdpkg/dashboard/api_inbox.go:24
POST/api/inbox/routeOwner onlyRoute one item: {source, item_id, destination: spek_rfc|dibs|dismiss, repo?} (202 queued; 400 unconfigured destination, 404 unknown item, 409 already queued/running)pkg/dashboard/api_inbox.go:25
POST/api/inbox/dismissOwner onlyBulk “Knowledge only”: {items: [{source, item_id}], undo?}pkg/dashboard/api_inbox.go:26
GET/api/inbox/settingsDashboard auth/sessionAuto-routing rules, default RFC repo, dibs URL, destination readinesspkg/dashboard/api_inbox.go:27
POST/api/inbox/settingsOwner onlyUpdate inbox.rules / inbox.spek.repo / inbox.dibs.url in the runtime config (omitted fields unchanged)pkg/dashboard/api_inbox.go:28
GET/api/inbox/{source}/{id}/contentDashboard auth/sessionFull text of one item: {title, summary, transcript, highlights, markdown, pending, provenance}, from the fact or live from the source while the fact has no text yet (404 unknown item, 502 source unreachable)pkg/dashboard/api_inbox.go:29
GET/api/inbox/{source}/{id}/audioOwner or read-writeMint a fresh presigned audio link for one item ({url, expires_at}, Plaud: 24h); never stored by the hive, replied with Cache-Control: no-store, audited as inbox_audio (403 role, 404 unknown item or no audio, 502 source unreachable)pkg/dashboard/api_inbox.go:30